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— 


Work-around: Users shouid be cautioned about opening the Chooser while the MIDI 
Manager is running. Unfortunately, this is tempting to do if one needs to disable AppleTalk 
during a MIDI session to use an extra port or guarantee better reception of MIDI. If the user 
finds that other programs cease to work because of port conflicts (usually port error -98), he can 
startup the MIDI Manager (running PatchBay is sufficient), then shut à down (by quitting 
PatchBay and any open MIDI Manager clients), then open and close the Chooser. This will reset 
the PRAM value of SPConfig. It is not sufficient to just open and close the Chooser without 
running the MIDI Manager. Also, zapping PRAM will not work. 


Future fix: No fix is planned for the MIDI Manager, although future versions of the 
Chooser may correct this problem. 


4. Large buffers cause errors on Mac Plus and SE 


Input buffers larger than 20K will cause SCC overrun errors during reception of full- 
speed MIDI on a Mac Plus and SE. This is because internal buffer management operations take 
too long when the buffer is large. Also, the operations of removing ports or signing clients out 
of the system can cause SCC overrun errors. 


Work-around: Request input buffers with sizes less than 20K, and try not to remove 
ports or sign out when fast MIDI data is being processed. 


Future fix: This bug will probably not be fixed in the next version of the MIDI 
Manager. 


5. Long readHooks may cause SCC overruns 


ReadHooks that take a long time to execute may cause SCC overrun errors during 
reception of large amounts of high-speed MIDI data (system exclusive messages, for example). 
This is especially true on a Mac Plus or SE. 


Work-around: Developers should be cautious about making trap calls or performing 
other time-consuming operations during readHook routines. The distinction between MIDI 
Manager buffer overflows and SCC overrun errors is important: If a readHook doesn't dispose of 
data quickly enough, it will cause MIDI Manager buffer overflows, if it takes too much time, 
regardless of how fast à actually handles data, it will cause SCC overrun errors. Note that the 
readHook may execute longer than 1 millisecond on occasion without causing SCC overruns. But 
if à always executes longer than 1 millisecond, problems will occur when large amounts of full- 
speed MIDI must be handled. 


Future fix: This limitation is caused by limits on CPU resources, and cannot be fixed. 
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THE FOLLOWING BUGS ARE FIXED IN VERSION 1.2; 


1. incorrect end-continuation flags (Version 1.1): 


In version 1.1, system exclusive messages that clients receive from the Apple MIDI 
Driver may not always have the correct end-continuation flags set This situation arises when a 
system exclusive message is terminated by an $F7 alone in a packet, and only if no mid- 
continuation packets were generated to hold part of the message. oe a a 
exclusive messages less than 251 bytes long (that is, 251 MIDI bytes, not packet length). For 
example, a system exclusive message 250 bytes long would normally be passed in a start- 
continuation packet containing the first 249 data bytes, followed by an end-continuation packet 
containing the final $F7. This bug causes the end-continuation packet to be marked as a normal 
packet instead. Note that the problem can be caused by a message less than 250 bytes long É 
there is a pause of more than 10 milliseconds before the $F7 byte, due to timeout handling of 
incomplete system exclusive messages. 

implications: A MIDI Manager client could become confused f it relies on 
continuation flags alone for processing of system exclusive data. 


2. SCC errors marked incorrectly (Version 1.1): 


In version 1.1, the Apple MIDI Driver notifies applications of SOC errors (such as SCC 
overrun and transmission errors) using packets that should be marked as MIDI Manager 
message packets. This bug causes them to be marked as normal packets. Also, the third byte of 
data in the packet contains a random value, instead of being 0 as the documentation claims. 


Implications: A MIDI Manager client may become confused if it treats the error 
packet as valid MIDI data. 
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About this document 


This manual describes the operation of the Macintosh® MIDI Manager and associated tools. 
Notes and warnings appear in boldface type. Fragments of program code and parameters that 
are meant to be typed to your computer appear in the Courier typeface. 


About the MIDI Manager 


The MIDI Manager Tool Set is a software toolkit that enables developers to create ports for MIDI data, and 
to transfer such data to and from MIDI devices connected to the Macintosh. The data can be passed among 
several applications running under MultiFinder™, or between logical ports within a single application. 

A separate MIDI driver allows the MIDI Manager to read and write MIDI data to the serial ports so that you 
don’t have to access them yourself. Additional MIDI drivers can be written to allow access to other types of 
hardware. The MIDI Manager assigns time stamps to each packet of MIDI data in any of a variety of formats, 
and converts from one format to another. 


The MIDI Manager Tool Set is actually made up of a number of pieces. This document describes the MIDI 
Manager and its timer and message handling facilities. It makes only passing mention of PatchBay™, a graphic 
interface for connecting ports; the Apple MIDI Driver, and SquidCakes, 2 minimal MIDI terminal with very 
simple sequence recording capabilities. (PatchBay will be completely described in a future document; to leam 
more about SquidCakes see the source code on the developer release disk.) 


Note: This document assumes that the reader has some familiarity with MIDL Readers 
wanting to find out more about MIDI are referred to the MIDI 1.0 Specification, available 
from the International MIDI Association or any of the increasing number of good books on 
MIDL 


How The MIDI Manager works 


The MIDI Manager operates through use of logical ports. These ports are virtual sources and sinks for MIDI 
data and are maintained entirely by the MIDI Manager. Your application can treat them as though they are 
actual communications ports, and many of the messy details of actually writing to and reading from the serial 
ports are handled for you. 


Installing the MID! Manager 


The MIDI Manager code is contained in an INIT file named “MIDI Manager”. To install the MIDI Manager 
move the MIDI Manager and the Apple MIDI Driver files into your System folder and restart your Macintosh. 
The MIDI Manager code will then be available to your programs. When the first application signs in, the MIDI 
Manager automatically loads MIDI drivers that are present in the System folder. It also > automaticaly disposes 
of MIDI drivers when the last application signs out. 


Signing in to the MIDI Manager 


Any application that uses the MIDI Manager must first sign in, becoming a MIDI Manager client. To sign in, 
an application passes a unique client identifier and a name to the MIDI Manager. Although the name can be any 
Pascal string, the identifier must be a 4-byte value of type OSType; an obvious choice for the identifier is the 
application's creator, or signature, because this 4-byte value is guaranteed to be unique to each application. 
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Creating ports 


An application that has signed in to the MIDI Manager can create MIDI ports through which to pass MIDI 
data. Each port an application creates can be either a time base, which provides the MIDI Manager's timing 
facilities, or a data port which is used to read and write MIDI packets. 


Each data port is either an input port or an output port; no data port can be both. To pass MIDI data you 
connect an output port to an input port, which is, in effect, just like connecting MIDI cables. A data port can 
be connected to several other data ports, automatically splitting outgoing data and merging incoming data as 
necessary. 

If a client needs time services it must create at least one time base. A time base can be connected to several 
ports, regardless of whether they are input, output or time ports. When the time base’s clock ticks, all clocks 
of all ports connected to it tick, synchronizing the clocks of all the connected ports. 

Normally an application will create a time base before creating any other ports. When the application does 
create another port, it passes the reference number of the time base in the initialization record of the new data 
port and the MIDI Manager automatically connects the new port to the time base. 


When a data port is connected to a time base the time base provides a clock for the data port. If a data port is 
not connected to a time base then the data port's clock remains at 0, and all MIDI packets passed through the 
data port are stamped with a time value of 0. 

You must take into account the way the MIDI Manager works when planning memory management. All data 
structures specific to a client are allocated in the client's heap. Most of these data structures are locked. All 
ports and buffers are locked when they are created because the MIDI Manager must access the data structures 
from interrupt level. Every effort is made to minimize fragmentation of the client's heap when allocating these 
blocks. When a client signs out, the MIDI Manager dealiocates any memory it has allocated for that client. 


When the MIDI Manager returns a handle to a data structure (such as a portinfoRec), that block is allocated in 
the caller's heap, but is not locked. The caller is responsible for deallocating the block when it is no longer in use 
because the MIDI Manager has no way to determine when the caller has finished with the block. 


identifiers and reference numbers 


Clients, data ports, and time bases can be distinguished either by identifiers or reference numbers. An identifier 
is a 4-byte value of type OSType. No two signed-in clients may have the same identifier, and no two ports 
created by the same client may have the same identifier. The MIDI Manager assigns reference numbers when 
applications create ports, and there is a unique reference number for every existing port. There are certain calls 
that are normally used by a client application to affect ports it has created. Calls that should not be made by a 
client other than the one that created the ports require a reference number. This minimizes the possibility that 
a client might affect ports that do not belong to it. 

When a dient looks for a port, it must specify a client identifier and a port identifier, or it must specify a 
reference number for one of its own ports. Patchers, that is, applications that create and manage MIDI ports, 
use identifiers to specify connections between objects that may or may not exist when the connection is 
specified. In general, any client or patcher may make calls that require an identifier, but calls that require a 
reference number may be made only by the client that created the port. 


MIDI Manager packets 


The MIDI Manager reads and writes data in variably sized packets up to 255 bytes long. Each 
packet begins with a 6-byte header containing one byte of flags, one byte indicating the length 
of the packet, and a 4-byte time-stamp. The data follows the header bytes. Packets must begin 
at word-aligned addresses. 
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The flags byte indicates, among other things, the type of the packet. The two packet types 
currently defined are the MIDI packet and the MIDI Manager message packet. A MIDI Manager 
message is used to inform your application of problems such as buffer overflow errors. 


MIDI packets normally contain a single complete MIDI message. MIDI system exclusive 
(SysEx) messages may be split into several sequential packets. In this case the flags indicate that 
data in a given packet continues in following packets. 

MIDI messages in packets are ‘sanitized’; that is, a MIDI message always contain a status byte 
even if the message was received from an external synthesizer with the status byte omitted by 
MIDI running status optimization. System exclusive commands always end with an $F7 byte. 
Real-time messages are sent in separate packets and never interrupt a normal MIDI message 
within a packet. You can count on this behavior when your application receives packets from the 
MIDI Manager, and the application must obey these rules when it writes MIDI packets. 


Reading MIDI data 


A port receives its data through its readHook. If the readHook is NIL then the packets are lost. The 
readHook is called when the timeStamp of a packet is less than the sum of the pon's current time and 
offsetTime. When this condition is satisfied, the packet is considered current. 


The value of offsetTime can be used to enable an application to read MIDI packets at a past or future time, 
for example in implementing a MIDI delay. If offsetTime is a large negative number then readHook will 
never be called. A client can be assured of receiving all data by setting offsetTime to a large positive value. 
Three constants are defined for use with readHook: midiGetEverything is a large positive value that 
specifies that readHook should receive all data; midiGetNothing specifies that readHook should receive 
no data; midiGetCurrent enables an application to get data at the time it was intended to be read. 


readHook may return any of three results to the MIDI Manager: 
1) midiKeepPacket The current packet is placed back in the buffer and readHook is not called again 
until: 


(one of the following:) 
e the clock ticks 
e offsetTime changes 
e another packet is received 
e the MIDIPoll call is made 
2) midiMorePacket The packet was read and removed from the buffer, and readHook will be called 
with any other current packets. 
3) midiNoMorePacket The packet was read and removed from the buffer, but the readHook is not 
called again until: 


(one of the following:) 
e the clock ticks 
e offsetTime changes 
e another packet is received 
e the MIDIPoll call is made 


Note: readHook may be called at interrupt level. 


Each time readHook is called, it is passed a pointer to the packet. The MIDI Manager will repeatedly call the 
readHook until there are no more current packets. 


The MIDI Manager never returns partial MIDI messages to clients, with one exception. System-exclusive 
messages may be split across multiple packets because of their variable size. 
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When multiple packets are available in the buffer associated with an input port, they are sorted and passed to 
the readHook in ascending order of time stamps. This does not mean that packets received by the 
readHook are always necessarily in ascending time order. For example, it is possible for the readiHook to 
read a packet with time stamp 20, and then for a packet to be placed in the buffer with a timestamp of 15. If 
these packets were in the input buffer simultaneously, however, the one with the lesser timestamp would be 
passed to the readHook first. Time sorting of messages is susceptible to round-off errors incurred during 
timestamp conversion if the data port's time base has been stopped. In this case, the MIDI Manager may 
change the order of messages. If a data port has no time base, messages are passed to the readHook in the 
ieee a ne ean ener di 
0 in this case). 


Writing MIDI data 


When a client writes data, à supplies a package that contains a header consisting of flags, length, and a time 
stamp followed by one or more MIDI messages. 


1 | 4 (Len - 6) 


Figure 1: MIDI packet format 


The MIDI Manager always writes packets immediately. The packet's final time stamp, as seen by the 
destination port, depends on the state of bit 7 of the packet flags. 

If bit 7 is clear, the MIDI Manager calculates an offset between the time stamp and the current local time of 
the output port. The final time stamp is computed by adding this offset to the current local time of the 
destination port. This guarantees that the relationship between the packet's time stamp and local time is 
preserved, even though the current local time may differ between the source and destination ports. 
Example: 


The timestamp of MIDI message 1 is 03:10.0 and it is written at 03:00.0. The current local time at the 
destination port is 04::00.0. If the packet is stamped with the local time of the destination then the relationship 
between that time stamp and local time has changed. The difference between the time stamp and the source 
port's local time is 00:10.0. To preserve this relationship, we have to add 00:10.0 to the destination's local time, 
giving the packet a final time stamp of 04:10.0. Note that the actual time at which the destination ports 
readHook is called depends on the value of the destination’s offsetTime. It may be earlier or later than 04:10.0. 
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Figure 2: Time stamp conversion 


If bit 7 of the flags is set, then the the current local time of the destination port is used regardless of the 
packet's time stamp. In the example illustrated in figure 2, if bit 7 of the flags were set then the final time 
stamp of the packet would be 04:00.0, the current local time for the destination. 


Timer facilities 


The MIDI Manager uses time ports to stamp MIDI data and to schedule periodic or one-time wake-up calls. 
Each time port may be synchronized either internally or externally. An internally synchronized time port simply 
runs in real time, beginning when an application starts it. An externally synchronized time port ticks only when 
connected to another time port that is running; it ticks when the port to which it is synchronized ticks. Such a 
port enables a client to synchronize to another client, or to the time bases supplied with the Apple MIDI 
Driver. Synchronization to the time bases supplied by the Apple MIDI Driver makes it easy to synchronize to 
incoming MIDI Time Code or MIDI clocks. 

If you want your application to allocate an intemally synchronized time port that other ports cannot connect 
to then you can request an invisible time port. Invisible time ports function identically to other type of time 
ports, but PatchBay doesn't display them. This characteristic prevents users from connecting other ports to 
the invisible time ports. 


Timer formats 


The MIDI Manager represents time in any of the following formats, and automatically ensures that a port 
receives timing information in its own format. 

e Milliseconds The time stamp contains the raw millisecond value read from the clients 
dock. In general, this value is the number of milliseconds that have 
elapsed since the client’s time base started. 

e Beats In this format the time stamp contains the number of MIDI clock ticks 
received since the clock was set to zero, that is, normally, when it was 
started. All of the MIDI Manager’s beat calculations are based on 960 
pulses per MIDI quarter note. The MIDI Manager assumes a tempo of 
125 beats per minute. 
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e MIDI Time Code In this format, the time stamp contains the raw number of SMPTE bis 
(80 per frame). (SMPTE stands for Society of Motion Picture and 
Television Engineers; the standard time code developed by this 
organization is commonly referred to as SMPTE Time Code, or, more 
simply, SMPTE.) This can be converted to the format in figure 3 using the 
call ConvertTime. Note that there is some rounding error inherent in 
converting from raw bits to quarter frames. 


Hours: Minutes: Seconds Quarter frames 
0-23 0-59 0-59 0-120 


Figure 3: MIDI Time Code format 


Packet handling 
In every MIDI packet there are 8 bits of flags. These flags contain information necessary for the correct 
interpretation of the packet. For packets containing MIDI channel voice messages, the usual value of the flag 
__ ate will be 0, making it easy to decode the flags. 
midiTimeStampValid or midiTimeStampCurrent is contained in bit 7 of the flag byte. A 
value of 0 specifies that the packet's time stamp should be used when adjusting time stamps, and a value of 1 
that the destination port's current time should be used. 
The packet type is contained in bits 4-6 of the flag byte. For MIDI packets, this field will be 000 b. A value of 
001 b indicates that the packet contains a non-MIDI message to or from the MIDI Manager (depending on the 
direction of the port). Currently, the only defined MIDI Manager packets are buffer overflow errors and errors 
from the MIDI driver. 
Note: For compatibility with future versions of the MIDI Manager, clients should check the 
packet type of all packets that they receive. If the application doesn't recognize the message 
type, then the message should be ignored. 
Bits 0-1 of the flags word contain information regarding continuation packets. This field will usually be 00, 
since most MIDI information is not broken up across multiple packets. Large SysEx commands will be broken 
up across multiple packets, so checking these bits can be critical to the correct interpretation of a message. 


Reserved bits must be 0 upon being written and should be masked when read. 
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Reserved; must be 0 


00 = New packet, not continued 
000 = MIDI packet 01 = Beginni i 
: - Beginning of continued packet 
001 = MIDI Manager packet 10 = End of continued packet 


11 = Continuation 
0- midiTimeStampValid 
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Figure é: MIDI Packet flag bits 


Length 
The length byte designates the length of the packet in bytes. This limits the data portion of the packet to a 
length of 249 bytes. 


Applications | 

The MIDI Management Tools disk contains several sample applications which are included to 
illustrate what you can do with the provided tools. These applications do not necessarily 
iltustrate the best way to accomplish the given tasks using the MIDI Manager. They should not 
be used as examples of how to write Macintosh applications. 
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MIDI Manager Calls 


The following pages describe alt of the function calls currently defined for the MIDI Manager. For each call, a 
description of the function is supplied as well as a description of the data structures used by that call. 
The declaration of each call is followed by a list of the call's idiosyncrasies. These idiosyncrasies may include any 
of the following: 

e the call can be made from an interrupt 

e the call may be made by the client 

e the call is usually made by patchers or other clients 

e the call is useful for time bases 

e the call is useful for data ports 
The MIDI Manager uses a new dispatch mechanism that will be shared between the MIDI Manager and future 
sound tools developed by Apple. This mechanism provides a method whereby an application can check for the 
existence of a sound tool it wishes to use. Since the MIDI Manager is an optional system software 
component, applications must check to see if it is installed using the SndDispVersion call before calling any 
MIDI Manager calls. 


SndDispVersion 
Function SndDispVersion(toolNum : Integer) : LONGINT; 
Idiosyncrasies 


e the call can be made from an interrupt 

e the call may be made by a client 

e the call is usually made by patchers or other clients 
e the call must be made before signing in 


This function returns the version of the MIDI Manager when called with toolNum = midiTooiNum = 4. 
This call must be made before the first call to MIDISignin to check if the MIDI Manager has been installed in 
the system. SndDispVersion returns 0 if the MIDI Manager has not been installed. Otherwise, the version 
retumed is in the standard Macintosh version number format. 


MIDISignin 


Function MIDISignin(clientID: OSType; 
refCon: LONGINT; 

icon : Handle; 

name: STR255) : OSErr; 


Idiosyncrasies 


e the call may be made by a client 
This call adds the client making the call to the list of clients. 
clientID must be unique across all clients signed into the MIDI Manager. Usually clientID wil be the 
application signature of the client. The refCon is a 4 byte field available for use by the client. If more than 4 
bytes of memory are needed then the refCon may be used to store a pointer to this additional memory. Icon 
is the handle of an icon that is displayed in PatchBay. Name is the print name to be used for the client in 
PatchBay. 
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Note: SadDispVersion must be called to check whether the MIDI Manager has been installed in 
the system prior to MIDISignln . 
Result codes: 


noErr No Error 
memFullErr Not enough room in heap zone 
dupIDErr A client has already signed in with that ID 


MIDISignOut 
Procedure MIDISignOut(clientID: OSType); 
Idiosyncrasies 
e the call may be made by a client 
This call will remove the client corresponding to clientID from the MIDI Manager, deailocating any memory 
that may have been allocated for that client and breaking any connections. Any pending input or output data is 
lost when this call is made. 
Note: The only calls that are legal after the MIDISignOut call has been made, or before 
MIDISignin has been made, are SadDispVersion and MIDISignin. 
MiDiGetCllents 
Function MiDIGetClients : MIDIIDListHdl; 
Idiosyncrasies 
e the call is usually made by patchers or other clients 


This call retums a handle to a structure containing the ClientiDs of all clients signed into the system. This 
handle is allocated in the caller's heap, and the caller is responsible for deallocating the memory. 


The resulting handle will be NIL if there was an error in allocating the memory block. 


Data Structures: 
MIDIIDList = 
RECORD 
numiDs : INTEGER; © 
list : Array [0 .. numiDs-1] of OSType; 
END; 


MiDiGetClientName 


Procedure MIDIGetClientName(clientID:OSType; 
VAR name : STR255); 


Idiosyncrasies 


e the call may be made by a client 
e the call is usually made by patchers or other clients 
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This procedure will return the print name of client in the VAR parameter name. The string returned is the 
string displayed by the PatchBay application as the client's name. A null string will be returned f there is no 
matching client. 

MiDiSetClientName 


Procedure MiDiSetClientName (clientID: OSType; 
name: STR255); 


Idiosyncrasies 

e the call may be made by 2 client 

e the call is usually made by patchers or other clients 
This procedure will set the print name of the client matchin g clientID to name. This string is displayed as 
the client’s name in the PatchBay application. If there is no matching dient, nothing is done. 
MiDiGetPoris 
Function MIDiGetPorts(clientiD: OSType) : MIDIIDListHdl; 

idiosyncrasies 

e the call may be made by a client 

e the call is usually made by patchers or other clients 


This call will return a handle to a structure containing the port!Ds of all ports signed into the system that 
belong to the client whose identifier is clientID. This handle is allocated in the caller's heap, and the 
caller is responsible for deallocating the memory. 


Data Structures: 
MIDIIDList = 
RECORD 
numiDs : INTEGER; 
list : Array [O .. numiDs] of OSType; 
END; 


MIDIAddPort 


Function MIDIAddPort(clientiD: OSType: 
bufSize: INTEGER; 

VAR refnum: INTEGER; 

init: MiDiPortParamsPtr) : OSErr; 


Idiosyncrasies 


e the call may be made by a client 


This call will create a new port configured using the information in the record pointed to by init. On return, 
refnum will contain the reference number of the port allocated by the MIDI Manager. Refnums are unique 
across all ports allocated by the MIDI Manager. 


Not al! of the information in the init record is used by all of the ports. Time bases don’t use the offsetTime 
or readHook fields. Data ports don’t use the initClock field. Time ports and output ports don’t use 
BufSize. 
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BufSize is a recommendation to the MIDI Manager for the size of the buffer to allocate for the port. In 


general the less frequently you plan on reading you messages, the larger a buffer you should allocate. The MIDI 
Manager will never allocate a buffer smaller than BufSize. The minimum buffer size the MIDI Manager will 


allocate is 1KB. 
Ports are always locked in memory because the MIDI Manager must access them at interrupt level. Every 
effort is made to allocate the port in such a way that the application heap doesn’t become fragmented. Clients 
should take this into account when adding ports. In general, ports should be allocated as early as possible in a 
client's startup sequence. 

Result codes: 


noErr No Error 
memFullErr Not enough room in heap zone 
vConneciMade A pending virtual connection to this port was resolved 
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Data Structures: 
MiDiPortParams = 


RECORD 
portiD :OSType; {ID of port, unique within client) 
portType : Integer; {Type of port - input, output, time, etc.} 
timeBase : Integer; {refnum of time base, O if none} 
offsetTime :LONGINT; {offset for current time stamps} 
readHook : Ptr; {routine to call when input data is valid} 
refCon : LONGINT; {refcon for port (for client use)) 
initClock : MIDICikinfo; (initial info for a time base} 
name : Str255; {name of the port) 

END; 


portType may have the following values: 


midiPortTypeTime = 0; {time port} 
midiPortTypelnput = 1; {input port} 
midiPortTypeOutput = 2; {output port} 
midiPortTypeTimeinv = 3; {invisible time port} 


offsetTime is specified in the units indicated by the format field in the intClock record. 


MIDICIkInfo = 

RECORD 
sync : Integer; {midilnternalSync, midiExternalSync} 
curTime :LONGINT: {current time for port} 
format : Integer; {time code format to use} 

END; 


Note: readHook may be called at interrupt level 
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MiDiGetPortinto 


Function MiIDiGetPortinfo(clientID: OSType; 
portiD : OSType) : midiPortinfoHdl; 


Idiosyncrasies 


e the call may be made by a client 
e the call is usually made by patchers or other clients 
e the cail is useful for time bases 
e the call is useful for data ports 
This call will retum a record containing the port type and time base of the port, along with all of its 
connections. The interpretation of the connections is dependent on the port type. For data ports, the ports are 
connections to other data ports. For time bases the connections are the ports deriving timing information 
from this port. 


Data Structures: 
MIDIIDRec = 
RECORD 
clientiD : OSType; 
portiD : OSType; 
END; 
Portinfo = 
RECORD 
portType "INTEGER; {type of port} 
timeBase * MIDNDRec; {MIDIDRec for time base} 
numConnects : INTEGER; {number of connections) 
cList : ARRAY [1..100] OF MIDIIDRec {the connections} 
END; 


MiDiConnectData 


Function MiDiConneciData(sourceClient: OSType; 
srcPort: OSType; 

destClient: OSType; 

destPort: OSType) : OSErr; 


Idiosyncrasies 


the call can be made from an interrupt 

the call may be made by a client 

the call is usually made by patchers or other clients 
the cail is useful for data ports 


This call connects two data ports together using the IDs of the ports and clients to specify the connection. 
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With this call it is possible to create virtual connections between ports that don't yet exist. If ether or both of 
the ports or clients don't exist, the MIDI Manager adds the connection to a list of pending connections that is 
checked whenever a port is created, and retums midiVConnectErr. This error informs that caller that the 
connection has not yet been made. Virtual connections are automatically resolved when both clients have 
signed in and both ports have been created. 


MiDiUnConnectData 


Function MIDIUnConnectData(sourceCllent: OSType; 
sourcePort : OSType; 

destClient : OSType; 

destPort : OSType) : OSErr; 


Idiosyncrasies 


e the call can be made from an interrupt 

e the call may be made by 2 client 

e the call is usually made by patchers or other clients 

e the call is useful for data ports 
This call disconnects two data ports. If it is a virtual connection, the connection is simply removed from the 
list of pending virtual connections and midivConnectRmvd is returned. 
Note that connections are not undone immediately. The MIDI Manager does not remove a connection while 
the sourcePort is writing data. This call should be used with care because it is possible to have problems 
with hanging notes, unfinished system exclusive packets, and other incomplete data. 


MiDiConnectTime 


Function MiDiConnectTime (sourceClient : OSType; 
sourcePort: OSType; 

destClient : OSType; 

destPort : OSType) : OSErr; 


Idiosyncrasies 


the call can be made from an interrupt 

the call may be made by a client 

the call is usually made by patchers or other clients 
the call is useful for time bases 

the call is useful for data ports 


This call tells the MIDI Manager that the destination's timing should be derived from the source port, which 
must be 2 time base. The call doesn't affect the time format of either port. If either of the ports or clients 
doesn't exist, then the MIDI Manager adds the connection to a list of pending connections that is checked 
whenever a port is created, and returns midiVConnectErr. This error informs the caller that the connection 
has not yet been made. Virtual connections are resolved when both clients have signed in and both ports have 
been created. 


This call may be used by a client to connect its data ports to a time base. A more efficient akernalive is to 
create the time base first and pass its refnum in the init parameter to MIDIAddPort. 


e © @ @ @ 
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MiDIUnConnectTime 


Function MIDIUnConnectTime(sourceClient: OSType; 
sourcePort: OSType; 

destClient: OSType; 

destPort: OSType) : OSErr; 


Idiosyncrasies 


e the call can be made from an interrupt 

e the call may be made by a dient 

e the call is usually made by patchers or other clients 
e the call is useful for time bases 

e the call is useful for data ports 


This call will remove the time connection between the two ports. When this happens, the clock of the 
destination port is reset to zero. Care should be exercised with this call because data may be trapped in the 
buffer when the clock stops. 

MIDIFlush 

Procedure MIDIFlush(refNum: Integer); 


Idiosyncrasies 


e the call can be made from an interrupt 
e the call may be made by a client 
e the call is useful for data ports 


This call simply clears out the data in the buffer of an input port It doesn't take into account the fact that 
notes may be playing. This call should be used with a great deal of caution. 

MiDiGetReadHook 

Function MIDIGetReadHook(refNum: Integer) : ProcPtr; 


Idiosyncrasies 


e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for data ports 
This call retums the readHook for the port corresponding to refnum. The readHook, if non-zero, is called 
whenever there is valid data written to an input port. 





Procedure MiDiSetReadHook(refNum: Integer, 
newhook: ProcPtr); 


Idiosyncrasies 
e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for data ports 
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Sets the port's readHook to newhook. newhook is called whenever a packet is ready to be received by the 
port. This happens when the time stamp of the packet is less than the sum of the port's current time and 
offset time. 

Note: the readHook will be called at interrupt level. 

The declaration for the readHook is: 
Function readHook(buffer: MIDIPacketPtr; refCon : LONGINT) : INTEGER; 
When readHook is called buffer will point to a buffer containing a single packet. The routine should copy 
the packet into the client's own memory and perform any additional processing necessary. refCon is 2 4 byte 
field whose value is specified in the MIDLAddPort call and can be modified by MIDiSetRefCon calls. A possible 
use for the refCon would be to differentiate a number of ports that share a common readHook routine. The 
ID of each port could be placed in each refCon so that the readHook could teli from which port the data 
originated. 
The result from readHook tells the MIDI Manager whether can dispose of the packet and whether or not 
to send more packets. Possible results are: 
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midikeepPacket “0, 
- save packet, don't send any more until: 
(one of the folowing:) 
e the clock ticks 
e offsetTime changes 


e another packet is received by the port 
e the MIDIPoll call is made 


midiMorePacket =1; 

- dispose packet and call with any other available packets 
midiNoMorePacket =2; 

- dispose packet, but don't send any more until: 


(one of the folowing:) 
e the clock ticks 
e offsetTime changes 
e another packet is received by the port 
e the MIDIPo!l call is made 
Data Structures: 
MiDiPacket = 
PACKED RECORD 
flags : BYTE; {assorted packet flags} 
length : BYTE; {length of the packet, incl header} 
tStamp :LONGINT; {time stamp of packet, in local time} 
data : PACKED ARRAY [0..248] of BYTE; {MIDI data} 
END; 


MIDIPacketPtr = ^ MIDIPacket; 


MiDiGetPortName 

Procedure MiDlGetPortName(clientiD: OSType; 
port : OSType; 

VAR name : STR255); 


Idiosyncrasles 


e the call may be made by a client 
e the call is usually made by patchers or other clients 
e the call is useful for time bases 
e the call is useful for data ports 


This procedure retums the name of the port specified in the VAR parameter name. The port name can be up to 
31 characters long. 
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MIiDiSetPortName 


Procedure MiDISetPortName (clientID: OSType; 
port : OSType; 

name : STR255); 

" Idiosyncrasies 


e the call may be made by a client 

e the call is usually made by patchers or other clients 
e the call is useful for time bases 

e the call is useful for data ports 


This procedure sets the name of the port specified to the string supplied. The name must not be more than 31 
characters in length. 
MiDIWakeUp 


Procedure MIDIWakeUp (refNum: Integer; 
baseTime : LONGINT; 

period : LONGINT; 

timeProc: ProcPtr); 


Idiosyncrasies 


e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for time bases 
This call allows a client to request either periodic wakeups or a one-time wakeup depending on the parameters 
passed to the call. MIDIWakeUp works correctly even when time runs backwards. 
If per iod is 0 then the supplied t imeP roc is called when the port's current local time crosses ba seT ime, 
either forwards or backwards. This happens when the current time becomes greater/less than ba seT ime. 
If the time code format of the port is milliseconds then baseTime is specified in milliseconds. If the 
format of the port is MIDI Time Code then baseTime is specified in SMPTE bits. If the format is beats, 
then baseTime is in 960ths of a quarter note. 
If period is non-zero, then period specifies an interval in clock ticks(based on the time code format of the 
port) at which timeProc will be called, providing a periodic interrupt to the client. baseT ime specifies a 
base from which to calculate possible wakeup times. Each of the possible wakeup times is a multiple of 
period dock ticks away from baseTime. t imeP roc will be called every time the port's current time 
crosses one of these possible wakeup times. 
Example: 
baseTime = 108, period = 10, and current time = 100 then possible wakeup times wouid be: 


78, 88,98, 108, 118, 128, 138, etc... 
and the timeProc would get called at 108, 118, 128, etc. 


If the current time suddenly jumped to from 100 to 155 then the t imeProc would get called at 155 and then 
again at 158, 168, 178, etc. The timeP roc is only called once no matter how many periods we might have 
skipped. The same is true if we had jumped backwards in time. 


The declaration for the timeProc is the following: 
Procedure timeProc (currentTime: LONGINT; refCon : LONGINT), 
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Note: timeProc will be called at interrupt level. 


MiDiRemovePort 
Procedure MiDIRemovePort(refNum: Integer); 
Idiosyncrasles 


e the call may be made by a client 

e the call is useful for time bases 

e the call is useful for data ports 
This call removes the port specified by refnum from the list of ports available to the client, disconnecting it 
from all other ports and deallocating any memory allocated for that port. Once a connection is gone, i is 
permanently unavailable. 


Warning: Do not attempt to remove or otherwise gain access to a nonexistent port. Calling 
MiDiRemovePort with a port that has already been removed can cause a bus error. 


MiDiGetSync 
Function MiDiGetSync(refNum: Integer): Integer; 


Idiosyncrasies 


e the call may be made by a client 
e the call is usually made by patchers or other clients 
e the call is useful for time bases 


This function returns the synchronization mode being used by the time port. This call is available only for time 
ports. Possible results are as follows: 
midiinternaiSync =Q; 


midiExternaiSync =}; 


MIDiISetSync 
Procedure MIDISetSync(refNum: Integer; 
sync : Integer); 

Idiosyncrasies 

e the call may be made by a client 


e the call is usually made by patchers or other clients 
e the call is useful for time bases 


This procedure sets the synchronization mode of a time port to the value supplied. Possible modes are as 
follows: 
midilnternalSync =Q, 


midiExternalSync =1; 
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MiDiGetCurTime 
Function MIDIGetCurTime(refNum: Integer): LONGINT; 
Idiosyncrasies 


e the call can be made from an interrupt 
e the call may be made by a client 
e the call is useful for time bases 


This function retums the current time for the port specified by refNum. If the time code format of the port 
is milliseconds, then the time is specified in milliseconds. If the format of the port is MIDI Time Code, then 
the time is specified in SMPTE bits. If the format is beats, then the time is in 960ths of a quarter note. 
MiDiSetCurTime 
Procedure MiDISetCurTime(refNum: Integer, 
time: LONGINT); 

idiosyncrasies 

e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for time bases 


This procedure sets the current time for the port to the supplied value. If the time code format of the port 
matching port is milliseconds, then time is specified in milliseconds. If the format of the port is MIDI Time 
Code, then time is specified in SMPTE bits. If the format is beats, then time is in 960ths of a quarter note. 


MiDiStartTime 
Procedure MiDiStartTime(refNum: Integer); 
Idiosyncrasies 


e the call can be made from an interrupt 
e the call may be made by 2 client 
e the call is useful for time bases 


This procedure starts running the clock associated with port number refNum, if the clock is internally 
zed. The dock is marked as having started in case the port is changed to intemal synchronization. If 

the port is changed to internal synchronization then the clock starts running. 
MiDiStopTime 
Procedure MIDIStopTime(refNum: Integer); 

Idiosyncrasies 

e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for time bases 
This procedure stops the clock associated with the port. The clock is marked as having stopped in case the 
port is changed to internal synchronization. 
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MiDiGetOffsetTime 

Function MIDIGetOffsetTime(refNum: Integer) : LONGINT; 
Idiosyncrasies 
e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for time bases 


This function will return the current offset time for the port. The offset time is added to the current time to 
determine whether packets are current and should be passed to the port's readHook routine. The offset time 
is given in the current time format of the port. 

MiDISetOffsetTime 


Procedure SetOffsetTime(refNum: Integer; 
offsetTime: LONGINT); 


idiosyncrasies 

e the call can be made from an interrupt 
e the call may be made by a client 

e the call is useful for time bases 


This procedure sets the offsetTime for the port referred to by refNum. The offsetTime is added to the 
current time to determine whether packets are current, and so should be passed to the port's readHook 
routine. The offset time is given in the current time format of the port. 
MIDIWorldChanged 
Function MIDIWorldChanged(clientiID: OSType) : BOOLEAN; 

Idiosyncrasies 

e the call can be made from an interrupt 


e the call may be made by a client 
e the call is usually made by patchers or other clients 


This function returns TRUE i something has changed in the world that a patcher might want to know about. 
It retums FALSE otherwise. The flag is deared when read. 


Things that might cause this routine to return TRUE include the following: 


e clients other than the current one signing in or out 
e ports being added or removed 
e connection being made or removed. 


client!D is the ID of the application making the MIDIWorldChanged call. 


MiDIGetRefCon 

Function MiDlGetRefCon(refNum: Integer): LONGINT; 
Idiosyncrasies 
e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for data ports 
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This function returns the contents of the port's refCon field. The refcon field is passed as an argument to 
the readHook of data ports and the timeProc of time bases. 
MiDiSetRefCon 


Procedure MiDiSetRefCon(refNum: integer; 
refcon : LONGINT); 

Idiosyncrasies 

e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for data ports 


This function sets the contents of a port's refCon field. The refCon field is passed as an argument to the 
readHook of data ports and the timeProc of time bases. 
MiDiGetCIReftCon 
Function MIDIGetCIRefCon(clientiD: OSType); LONGINT; 
Idiosyncrasies 
e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for data ports 


This function retums the contents of the client's refCon field. The contents of the client’s refCon field are 
available only through the MIDIGetCIRefCon and MiDISetCiRefCon calls. 


MiDISetCiRefCon 
Procedure MiDiSetCIRefCon(clientiD: OSType; 
refcon : LONGINT); 

Idiosyncrasies 


e the call can be made from an interrupt 
e the call may be made by a client 
e the call is useful for data ports 


This function sets the contents of the client's refCon field. The contents of the client's refCon field are 
available only through MIDIGetCiRefCon and MIDISetCiRefCon. 
MiDiGetTCFormat 
Function GetTCFormat(refNum: Integer): Integer; 
Idiosyncrasies 
e the call can be made from an interrupt 


e the call may be made by a client 
e the call is useful for data ports 


This function returns the current time code format of the port. Possible formats are: 


midiFormatMSec = 0; {milliseconds} 
midiFormatBeats = 1; {beats} 
midiFormat24fpsBit = 2; {24 frames/sec.} 
midiFormat2SfpsBit = 3; (25 frames/sec.} 
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midiFormat30fpsDBit = 4; {30 frames/sec. drop-frame} 
midiFormat30fpsBit = 5; {30 frames/sec.} 


MIDISetTCFormat 


Procedure MiDiSetTCFormat(refNum: integer; 
format : integer); 

Idiosyncrasles 

e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for data ports 


This function sets the time code format of the port See MIDIGetTCFormat for possible time code 
formats. 
MiDiConvertTime 


Function MiDiConvertTime(srcformat: Integer; 
dstformat: Integer; 
time : LONGINT): LONGINT; 


idiosyncrasies 


e the call can be made from an interrupt 
e the call may be made by a client 


This function will convert between one time code format and another. It allows an application to access the 
MIDI Manager's time conversion routines. Possible formats are as follows: 


midiFormatMSec = 0; {milliseconds} ( | 
midiFformatBeats = 1; {beats} . 
midiFormat24fpsBit = 2; {24 frames/sec.} 
midiFormat25fpsBit = 3; (25 frames/sec.} 
midiFormat30fpsDBit = 4; {30 frames/sec. drop-frame} 
midiFormat30fpsBit = 5; {30 frames/sec.} 
midiFormat24tpsQF = = 6; {24 frames/sec. longint format} 
midiFormat25fpsQF = 7; (25 frames/sec. longint format} 
midiFormat30fpsDQF = 8; {30 frames/sec. drop-frame longint 
format} 
midiFormat30fpsQF = 9; (30 frames/sec. longint format) 


For calls other than MIDIConvertTime, only formats 0-5 are valid. MiDIConvertTime should be called to 
coerce the time into one of the legal formais. 


Note: With any time conversion there is a possibility of rounding error. 


Macintosh MIDI Manager Tool Set Developer Notes | % 


MiDiWritePacket 


Function MiDiWritePacket(refNum: Integer; 
packet: MIDIPacketPir) : OSErr; 


Idiosyncrasics 

e the call can be made from an interrupt 
e the call may be made by a dient 

e the call is useful for data ports 


The packet pointed to by packet is written to the output port specified by refnum. Packet must specify 
an even (word-aligned) address. 

When a message is written to a port, it is simultaneously written to all ports that are connected to it. Time 
stamps are adjusted and the format is converted as necessary. MIDIWritePacket returns when the 
message has been written to all the ports linked to this port. An error is returned É the MIDI Manager was 
unable to write the packet to all of the connected ports, due to buffer overflows on one or more of the 
receiving ports. 

MIDIPoll 


Procedure MIDIPoll{refNum: integer; 
oftsetTime: LONGINT); 


Idiosyncrasies 

e the call can be made from an interrupt 

e the call may be made by a client 

e the call is useful for data ports 
The readHook of the port corresponding to refnum is called if there are packets in its buffer with time 
stamps less than the sum of the port's curTime and the offsetTime argument to this call. In effect, this 
offset time temporarily overrides the offset time associated with the port. 
This call tells the MIDI Manager to look for current packets. It calls the readHook at whatever interrupt level 
MIDIPoll was called. If à is important that a port's readHook never be called at interrupt time then you can 
set the port's offsetTime to midiGetNothing when the port is created. When the application polls for MIDI 
input, it can make the MIDIPoll call with the offsetTime set to midiGetCurrent. This method can be 
used to poll for MIDI input, while guaranteeing that the port's readHook wont be called at interrupt level. In 
general, readHook routines should be callable from interrupt level for best performance. 


MiDiGetClienticon 

Function MIDiGetClienticon(clientiD: OSType) : Handle; 
idiosyncrasies 
e the call may be made by a dient 
e the call is usually made by patchers or other clients 


This function retums a handle to the icon that was passed by the specified client at the time i executed the 
MIDISignin call. This call is useful for patchers which may need to show the icon associated with each client 
that is currently signed in to the MIDI Manager. 
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MiDiSetRunkRate 


Procedure MiDiSetRunRate(refnum: Integer; 
rate: Integer; 
stopTime: LONGINT); 


Idiosyncrasies 

e the call can be made from an interrupt 

e the call may be made by a client 
This call allows a client to adjust the rate at which an internally-synchronized time port is updated. This is 
useful for drivers that need to interpolate time values between the receipt of time code messages. The rate 
parameter specifies how many units the time port will be updated during a 128-uni interval. A value of 256, for 

_ would run the clock at 2 times normal speed. The stopTime parameter designates a time at which 

the time port will be stopped (as if MIDIStopTime had been called). This capability is important for drivers 
that need to ensure that the current time value does not exceed the value of the next time code message to be 
received. 
This call is not designed to maintain reasonable accuracy over time intervals greater than 100 milliseconds. Note 
that it will automatically start a previously stopped time port, and will stop a running time port if the 
stopTime is reached. 
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Summary of MIDI Manager data structures 


CONST 


midiToolNum 
midiMaxName 


{ time formats } 
midiFormatMSec 
midiFormatBeats 
midiFormat24fpsBit 
midiFormat25fpsBit 
midiFormat30fpsDBit 
midiFormat 30fpsBit 


{ the following time 


midiFormat24fpsQF 
midiFormat25fpsOF 
midiFormat 30fpsDOF 
midiFormat30fpsQF 


{ synchronization } 
midiInternalSync 
midiExternalSync 


{ port types } 
midiPort TypeTime 
midiPortTypeInput 
midiPortTypeOutput 
midiPortTypeTimeInv 


{ offset times } 
midiGetEverything 
midiGetNothing 
midiGetCurrent 


Macintosh MIDI Manager Too! Set 


31; 


am 


tool number for SndDispVersion |) 


max. chars. for names } 


milliseconds } 

beats } 

24 frames/sec. } 

25 frames/sec. } 

30 frames/sec. drop-frame } 


30 frames/sec. } 


formats are legal only for MIDIConvertTime } 


6; 
T; 
8; 


{ 
{ 
{ 
{ 


24 frames/sec. LONGINT format } 
25 frames/sec. LONGINT format | 
30 frames/sec. drop LONGINT fmt } 
30 frames/sec- LONGINT format |) 


internal sync } 


external sync } 


time port } 

input port } 

output port } 
invisible time port } 


S7FFFFFFF; { get all packets } 
$80000000; { get no packets } 
$00000000; { get current packets } 


Developer Notes 


{ masks and values for 


midiContMask 
midiNoCont 
midiStartCont 
midimMidCont 
midiEndCont 


midiTypeMask 
midiMidiType 
midiMgrType 


midiTimeStampMask 
midiTimeStampCurrent 
midiTimeStampValid 


MIDIPacket flags } 


$03; 
$00; 
$01; 
$03; 
$02; 


$70; 
$00; 
$10; 


$80; 
$80; 
$00; 


{ 
{ 
{ 


o an 


em qui 


mask for continuation bits } 
not a continued message } 

first packet of continued msg } 
middle of continued message | 


final packet of continued msg } 


mask for packet type } 
packet contains MIDI data } 
packet is MIDI Manager message } 


mask for time stamp type |) 
put current time in time stamp } 
use time stamp in packet |) 


{ command words in midiMgrType packets (the first word in the 
data field of an MIDIPacket) } 


= $0001; { input buffer overflow } 


midiOverflowErr 
midiSCCErr 
midiPacketErr 


= $0002; 
= $0003; 


{ 
{ 


{ results returned by readHooks 


midiNoReadPacket 
midiMorePacket 
midiNoMorePacket 


{ errors } 
midiNoClientErr 
midiNoPortErr 
midiTooManyPortsErr 
midiTooManyConsErr 
midivConnectErr 
midivConnectMade 
midivConnectRmvd 
midiNoConErr 
midiWritePcktErr 
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0; 


{ 


serial transmission error } 


MIDI msg had incorrect length } 


} 
save this packet for later } 


l; { ready for more packets } 
2; { don't want any more packets now | 
-250; 4 no client with that ID found ) 
«251; ( no port with that ID found | 
-252; 4 too many ports in the system } 
-253; { too many connections in system } 
-254; { pending virtual connection | 
-255; { virtual connection resolved | 
-256; 4 virtual connection removed | 
-257; { no connection between ports } 
-258: 4 couldn't write to all ports } 
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TYPE 
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midiNameLenErr = -259; 
midiDupIDErr = -260; 
midiInvalidCmdErr = -261; 


{ packets } 

MIDIPacket = PACKED RECORD 
flags : BYTE; 
length : BYTE; 
tStamp : BYTE; 
data : 

END; 


MIDIPacketPtr = ^ Packet; 


{ clocks } 
MIDIClkInfo = RECORD 


sync : Integer; 
curTime : LONGINT; 
format : Integer; 


END ; 


{ client information } 


MIDIIDList = RECORD 
numIDs : Integer; 
list : Array [0 
END ; 


{ name too long } 
{ duplicate client ID } 
{ cmd not supported for port type ) 


PACKED ARRAY [0..248] or BYTE; 


{ midiInternal/ExternalSync |) 
{ current value of port’s clock } 


{ time code format } 


.-100] of OSType; 


MIDIIDListPtr = * MIDIIDList; 


MIDIIDListHdl = * MIDIIDListPtr; 


{ port information } 


MIDIPortParams = RECORD 


portID : OSType; 
portType : Integer; 
timeBase : Integer; 


offsetTime : LONGINT; 


{ port ID, unique within client } 
{ type of port } 

{ refnum of time base, 0 if none } 
{ offset for time stamps ) 
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readHook : ProcPtr; { if <>0, call when data valid } 


refCon : LONGINT; { refcon for port (client use) } 
initClock : MIDIClkInfo; { info for a time base } 
Name : STR255; { print name of port for patcher |) 


END; 


MIDIPortParamsPtr = * MIDIPortParams; 


MIDIIDRec = RECORD 
client ID : OSType; 
port ID : OSType; 


MIDIPortinfo = RECORD 


portType : Integer; { type of port } 

timeBase : MIDIIDRec; { MIDIIDRec for time base } 

numConnects : Integer; { number of connections } 

cList : ARRAY [1..100] of MIDIIDRec { connections } 
END; 


MIDIPortInfoPtr = ^ MIDIPortInfo; 
MIDIPortInfoHdl = ^ MiIDIPortInfoPtr; 
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Appendix A - The Apple MIDI Driver 


The MIDI Manager supports special driver clients that are automatically started whenever the first non-driver 
client signs in to the MIDI Manager. MIDI drivers are shut down when the last non-driver client signs out of 
the MIDI Manager. 


The Apple MIDI Driver is a driver client that is supplied to enable MIDI input and output using an Apple MIDI 
Interface (or compatible interface) attached to the Macintosh's built-in modem or printer serial port. 


The user can select which serial port he or she wishes to use (or both, if desired) by opening the panel 
associated with the Apple MIDI Driver in PatchBay. This panel enables the user to choose the desired time 
code type, whether time code output is generated automatically, and whether the time base used by the Apple 
MIDI Driver is synchronized to a time port supplied by an application. Small icons are highlighted when the 
Apple MIDI Driver is receiving MIDI data or time code data. 


MIDI Input 


The Apple MIDI Driver parses all incoming MIDI data and produces clean MIDI Manager packets. Each packet 
contains one complete MIDI message (unless it contains parts of long system exclusive messages, which may 
be broken into multiple packets with appropriate continuation flags). Each message begins with a MIDI 
status byte. MIDI data that is transferred using running status is expanded to include the missing status byte 
for ease of handling by applications reading the packets. Likewise, a system exclusive message is always 
terminated by an $F7 byte even if à was transmitted without this byte. 

System real-time messages, which may interrupt normal MIDI messages at any time, are passed on 
immediately in their own packets instead of being interleaved with normal MIDI data. For example, a real-time 
message that arrives in the middle of a note-on message is sent as a single-byte packet, followed by the packet 
containing the note-on message when the remaining data bytes are received. 


Active sensing bytes (value = $FE) are always filtered by the Apple MIDI Driver and are not passed on to 
applications. 

The Apple MIDI Driver supplies a time stamp for each packet based on the time when the first byte of the 
message was received. By the time the last byte of the message is received and the packet is actually written 
to the MIDI Manager, the time stamp may already be in the past, especially for long system exclusive 
messages. This fact should not adversely affect applications, but may appear puzzling at first. The longest 
possible packet will appear to have been written about 80 milliseconds in the past when your application 
actually receives t. 


Time Code Input 


The Apple MIDI Driver recognizes beat-based timing dock messages as well as MIDI Time Code at 24, 25, 30 
drop-frame, or 30 frames per second. The particular format (or none) is selected by the user in the Apple MIDI 
Driver pane! in PatchBay. The driver's time base is driven by time code messages in the selected format unless 
the driver's time port is synchronized to another time port in the system. To provide maximum accuracy, the 
passage of time is interpolated between receipt of time messages. This means that time stamps are accurate 
to approximately millisecond resolution even though time messages might arrive via MIDI 4 a much slower 
rate. 

When no time code format is selected, all received time messages are simply passed along to the MIDI Manager 
without any special notice of their time information. If beat-clock format is selected, all MIDI Time Code 
messages are passed along without interpretation. Likewise, beat-clock messages are passed along when MIDI 
Time Code is selected. if a MIDI Time Code format is selected, the Apple MIDI Driver notices any change of 
frame rate, and automatically changes to the new frame rate. It alerts the user if this happens. 


Macintosh MIDI Manager Tool Set Developer Notes | B 


When receiving beat clock messages, the Apple MIDI Driver does not advance the clock unless it has received a 
MIDI Start or Continue message. 


To reduce system overhead and redundant information, the user may filter time code messages by checking 
the appropriate box in the Apple MIDI Driver panel. When this box is checked, the Apple MIDI Driver will not 
write packets to the MIDI Manager that contain timing messages in the selected time format. If the current 
format is MIDI Time Code, for example, all packets containing quarter frame and full MIDI Time Code 
messages are deleted from the input stream before they are written to the MIDI Manager. If beats are 
selected, only beat clock messages ($F8) are filtered; Start and Continue messages continue to be passed to the 
MIDI Manager. 

We strongly suggest that application developers assume that the Apple MIDI Driver performs all 
interpretation of timing messages, and that applications derive their MIDI-dependent time bases by 
synchronizing to the time port of the Apple MIDI Driver instead of interpreting time code messages 
themselves. This is important from a standpoint of efficiency and system overhead as well as conceptual 
cleanliness throughout the system. 


Error Handling 


The Apple MIDI Driver detects and passes on several types of errors. In many situations, applications 
receiving these errors should alert the application user to a potential problem, because each can indicate possible 
loss of arbitrary amounts of MIDI input data. It is probably not too pessimistic to assume that note-off 
messages might have been lost for any of the notes that are currently on, resulting in hanging notes. 


SCC Error. The Apple MIDI Driver flags any packet that was received with serial transmission errors. In this 
case, the packet is sent as a MIDI Manager message (packet flags = $10), the first word in the data section of 
the packet will be $0002, the second word in the data section will be either $0020 or $0040, and the erroneous 
MIDI data will follow: 


flags = $10 (MIDI Manager message) 

length = xx 

time = COOK 

error code = $0002 

error info = $0020 or $0040 

incorrect MIDI data follows... 
The error info value identifies the type of SCC error. A value of $0020 indicates an SCC overflow. This can occur 
if any code in the system executes for longer than 1 millisecond with serial interrupts disabled. It can also 
occur if the system is so busy that the Apple MIDI Driver gets more than 512 characters behind in processing 
MIDI data. In either of these cases, the only cure is to reduce demand on the system or rewrite at least parts 
of the application. 
An error info value of $0040 indicates a serial framing error. This typically occurs when MIDI cables are being 
plugged and unplugged or if there is an intermittent connection. 
Ilegal MIDI Message. If the Apple MIDI Driver detects an incorrect number of data bytes in a MIDI 
message without a corresponding serial transmission error, it will flag the packet as a MIDI Manager message. 
The first word in the data section of the packet will be $0003, the second word in the data section will be $0000, 
and the erroneous MIDI data will follow. For example, see table A-1. 


flags = $10 (MIDI Manager message) 
length = xx 

time = XOX 

error code = $0003 

error info = $0000 

incorrect MIDI data follows... 
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Table A-1: Illegal MID! message format 


An erroneous MIDI message might originate from faulty equipment or programming on another computer, 
em often will result from an intermittent MIDI connection or someone plugging and unplugging MIDI 


Note that fast MIDI data may also outrun the size of your input buffer. In this case, the MIDI Manager (not 
the Apple MIDI Driver) returns to the application a MIDI Manager message with $0001 in the first word of the 
packet's data section. It is usually possible to avoid this error by increasing the size of the application's input 
buffer, or rewriting the application to accept packets more quickly. 


MIDI Output 


The Apple MIDI Driver currently transmits only normal MIDI packets it receives from the MIDI Manager. 
The current version ignores all other packet types. A future version of the driver may transmit non-MIDI 
packet types in an Apple-defined system-exclusive format. 

The Apple MIDI Driver performs correct running-status optimization when transmitting MIDI messages. A 
time-out mechanism ensures that a MIDI status byte is sent whenever MIDI output has been idle for over 
half a second. 


Because the Apple MIDI Driver transmits MIDI messages at maximum MIDI transfer rates, it is sometimes 
necessary to break system exclusive messages into multiple continued packets that are smaller than usual in 
order to accommodate equipment that can't handle the full MIDI bandwidth. Slower transfers can be 
achieved by manipulating the time stamps of such packets. 

The Apple MIDI Driver requests only the default input buffer size from the MIDI Manager, so & is possible 
“ for an application to overrun the driver É t writes too many packets too quickly (or too far into the future). 
Applications should be designed to avoid this situation, and should test the result from MIDIWritePacket 
calls. If overruns are not avoided (or at feast detected and handled), you can expect lost MIDI messages and 
hanging notes. 


Time Code Output 


The Apple MIDI Driver automatically generates time code output if the user has selected a time code format 
and has checked the time code output checkbox in the driver's PatchBay panel. Output may be in beat clocks, 
or MIDI Time Code at 24, 25, 30 drop-frame, or 30 frames per second. Time code output is most useful when 
the Apple MIDI Driver is synchronized to an application's time port and the "Application Sync’ checkbox is also 
checked. 


Output of time code is only performed when time is running forward. If time skips forward or backward, the 
Apple MIDI Driver sends a Song Position Pointer or MIDI Time Code Pull Message in order to inform receivers 
of the new time value. Beat dock messages are not generated for times outside the range of legal song 
position pointer values. 
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Appendix B - MIDI Manager Tips 


Since the MIDI Manager is an optional part of Macintosh System Software, applications should 
check to see that à has been loaded before calling any MIDI Manager routines (including 
MIDiSignln). Users of high-level languages can accomplish this simply by calling the 
SndDispVersion call with midi Too1Num as the parameter. If the SndDispVersion function 
retums a non-zero result, the MIDI Manager is loaded and the application can proceed with a call 
to MIDISignin. The high-level language glue code for the SndDispVersion cali automatically 
checks to see if the appropriate trap is defined before attempting to execute à. Assembly 
language programmers must check the SoundDispatch trap ($4800) to ensure that it is defined 
before making the SadDispVersion call. 


After successfully executing the SadDispVersion and MIDISignin calls, most applications will 
wish to add input, output, and time ports. Although these ports may be added and removed at 
any time during the execution of an application, we suggest that applications add all ports near 
the beginning of execution, and remove them shortly before quitting. This helps minimize 
fragmentation of the heap. It also allows resolution of virtual connections. Although there may 
be compelling reasons for MIDI drivers to add and remove posts as the corresponding hardware 
channels are enabled and disabled, we discourage applications from doing so. When a port is 
removed all of its connections are lost, including any pending virtual connections. These 
connections will not be automatically recreated if the port is added again. 


The 4-byte port ID field of the MIDIPort Params record in the MIDIAddPort call identifies 
the port so that other applications can request connections to it. It also determines the order in 
which an application's ports are displayed in the PatchBay application. Ports are sorted in 
ascending alphabetic order. We recommend that time ports be displayed above the data ports 
that are synchronized to them. 


We also recommend that an application's input and output ports be displayed in the reverse order 
of that used by the Apple MIDI Driver. MIDI drivers should use the same ordering as the Apple 
MIDI Driver. This allows applications to be connected to drivers (the most common type of 
connection) in PatchBay without crossing wires. 


Automatic Connections 


Connections between ports can be made in three ways: 1) applications can request connections 
by calling MIDIConnectData and MIDIConnectTime, 2) users can manually set up connections 
using PatchBay, and 3) a network of connections can be saved and reloaded using PatchBay 
configuration files. 


An application may establish default connections for its ports if no connections have already 
been established at the time it starts up. By automatically making default connections, your 
application will relieve the user from starting PatchBay to manually set up port connections 
every time he or she runs your application. Your application will know that connections have 
already been established if any MIDLAddPort call retums a midivConnectMade error. In 
this case, your application should assume that & has already been connected in a desirable manner 
and should avoid requesting any connections itself. One of the ways this can happen is when the 
application is launched after the user loads a PatchBay configuration file. 
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The user should be allowed to change the default connections. One way to do this is to call 
MIDIGetPortinfo for each of your ports when your application is about to quit. The 
MIDIPort InfoRec retumed from MIDIGetPortinfo will have information on the 
connections to that port. You can save the information required to make the connections in a 
resource and recreate them when your application is run again. However, you should only save 
connection information if the application's ports were not connected when à started. 
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Macintosh Plus / SCSI Developer Information 


This is a “starter kit” for developers of add-on SCSI (Small Computer Systems Interface) 
products for Macintosh. It is intended for those developers working on SCSI-based products; 
most developers do not need to know about SCSI (for instance, whether or not a particular 
volume is on an SCSI drive is hidden by the file system, and is generally of no interest to an 
application). | 


What vou need for SCST development 
This section contains the following documents: 


e “Macintosh SCSI Developer Information”: This document, an overview of the 
development process for SCSI on Macintosh. 


e “Example SCSI Blocked-Device Driver": a document describing a sample SCSI disk 
driver. 


« "Patches to the SCSI Manager": a document covering known bugs in the ROM-based 
SCSI Manager software, and information on how we've fixed them. 


Elsewhere in this package, you ll find: 


e The SCSI Manager chapter of Inside Macintosh Volume IV: an overview of ROM-based 
software support for SCSI devices. 


e On diskette: source code for the sample driver, and SCSI-related equates. 


A 
Nort included in this package is this other important information: 


«Information about the proposed Small Computer System Interface standard (American 
Natonal Standard Committee draft proposal ANSC X3T9.2/82-2). 


¢ Information about the SCSI device you are connecting to Macintosh (in particular, 
information about the SCSI controller used by your device to manage communications 
on the SCSI bus). 


¢ Ofcourse: Inside Macintosh, "Outside Apple”, and the Software Supplements! 
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How to proceed 
It's important to have a working knowledge of how SCSI works, and how your device works; 
read the ANSC draft document and the manual that came with the SCSI controller you're using. 


Once you understand SCSI and your device, you're ready to look into how SCSI relates to 
Macintosh. Read the SCSI Manager chapter of Inside Macintosh; it covers software in the 
Macintosh ROM used to manage SCSI communications. “Patches to the SCSI Manager” will 
explain several problems in the ROM-based code, along with how they can be avoided. 


Study the sample driver source code and documentation. They show a number of “real-life” 
pitfalls (& workarounds) involved in adding a SCSI blocked device to Macintosh Plus. 


You will probably find it helpful to acquire a logic analyzer to aid in your development, if you 
contact Technical Support to ask for help with a problem (like "I'm losing bytes:"), we'll ask 
what you saw when you looked for the problem with an analyzer! 


ine 
The sample driver included in this package is not intended to be shipped as a product; it is 
therefore not licensable. It is provided to show how such a driver might be written (by someone 
with nota lot of time to tell developers how to write drivers! [see note below]). 


You must still license the System and Finder if you want to ship them with a product; please 
contact Apple's Software Licensing department at (408) 973-4667 for more information. 


n out help from Devel hni S 
The Developer Technica! Support group is chartered to assist developers in creating Macintosh 
(and Apple I) products for marker. Unfortunately, if you happen to have gotten a good deal on 
an old 370-megabyte cartridge drive that you want to hook up to your Macintosh, we cant really 
help you (there are only six of us for all Macintosh development, and four thousand of you). 


Whether or not you're working on a product for market, you may be able to get assistance from 
various independent developers groups, or from various consultants who specialize in Macintosh 
development (see the classified ads in the back of “Outside Apple”, or write to us at the technical 
support address below and perhaps we can recommend somone). 


If you are developing products for market, you should be a Certified Developer. It's free, and 
gets you mail or electronic-mail technical support, developer's discounts on Apple products, and 
a subscription to "Outside Apple". For more info, write to Apple Developer Relations, M/S 3-W, 
20525 Mariani Avenue, Cupertino CA 95014. 


If you're a Certified Developer and are developing a product and come upon a stumbling block, 
and this documentation doesn't help you over it, you can ask us for help. We answer technical 
questions from Certified Developers, via U.S. Mail (at the address below), via MCI Mail 
(mailbox "MACTECH"), or by telex (6502150798), generally with less than three days 
turnaround; however, please do your best to solve the problem on your own before asking us for 
help (also, please bear in mind that we're Macintosh experts, not really SCSI experts!). 


If you have comments or suggestions about the enclosed materials, we'd like to hear them; please 
write to us at this address: 


Apple Developer Technical Support: SCSI 


20525 Mariani Avenue, M/S 3-T 
Cupertino, CA 95014 
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Example SCSI Driver for Macintosh Plus 


O 
This document describes an example SCSI blocked-device driver for Macintosh Plus. 


This document and the accompanying software are directed at SCSI devices which can be used as 
disk drives by the Macintosh File Manager. No attention is paid to non-disk devices (such as 
archive tape drives, printers, etc); further specifications are planned for these kinds of devices 
(watch for news in future Software Supplements, and "Outside Apple”; if you have input to these 
specifications, please write to Apple Developer Technical Support, Attn: SCSI, 20525 Manani 
Ave M/S 3-T, Cupertino, CA 95014). 


This driver is an example to help get you started on your own driver, it is not intended as finished 
software. There are several “interesting” problems which must be overcome to get an SCSI 
blocked-device driver running on Macintosh; this software is intended to help you over these 
hurdles with a minimum of delay. Do not, however, assume that this software is bug-free; Apple 
Computer will not be responsible or liable for this software (or documentation) in any way. In 
fact, the previous version of this software (dated 26 March 1986) contained several errors which 
we didn't catch until after the package had shipped! (The ones we've found out about are fixed in 
this version, and noted at the bottom of this document. This version probably contains a new set 
of bugs!) 


The example driv 

The example driver grew out of one written by Macintosh Software Engineenng to allow them to 
test the ROM-based SCSI Manager routines. It has been rewritten and commented to help 
third-party developers to get their SCSI devices running on Macintosh with a minimum of effort. 


The driver was not written to be a clear example of how to write drivers; this driver attempts to 
show workarounds for the many problems which had to be dealt with in bringing up an SCSI 
hard disk, usually without explaining why all the workarounds are there. 


Note that there are several desirable features missing from this driver; for instance, it only 
supports one non-partitioned non-ejectable volume per SCSI controller. If your device supports 
multiple drives on one SCSI controller, partitioning, or ejectable cartridges, you will want to add 
support for these features to this driver. In writing this driver, the emphasis was on Macintosh 
system issues, not on SCSI functionality; as a result, some areas of the driver's design have 
suffered (error handling, for instance). 

A few notes about booting from an SCSI device 

The process used to boot off of SCSI devices is described in the SCSI Manager chapter of /nside 
Macintosh Volume IV. 


SCSI drivers are unique in that they are not in ROM and not in the System file. Normally, the 
ROM only knows about the ROM-based drivers at boot time. For SCSI, code was added to the 
ROM (we'll call it SCSIBoot, though it's not an externally- accessible routine) to allow drivers to 
be read in from disk before the system looks for volumes from which to boot. To keep the ROM 
simple, most of the work of loading an SCSI driver is left to the driver itself; that is, the code 
which is read in is assumed to be executable, and is given control so that it may install a driver in 
the system (in the example driver, you'll see that the first thing in the driver is not the normal 
driver header, but a branch to a routine which hooks the driver to the unit table, etc.). 


The SCSIBoot code in the ROM makes no assumptions about the code it loads and transfers 
control to. SCSIBoot itself is called by the normal boot code, which uses the following sequence 
to boot Macintosh: 


+ Call SCSIBoot to find SCSI devices which might be bootable 
¢ Start at the beginning of the drive queue 
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¢ If there's another drive there: 
* Try to read the boot blocks from it. 
¢ If the boot blocks are valid: 
¢ Try to mount the volume on that drive... etc. 
e If we can't read the boot blocks, or mount, or can't find System, etc: 
e Give the driver an “eject” control call. 
* Ifthe driver retums an error, assume it's non-ejectable: don't try to boot from it 
next time through the drive queue. 
« If we haven't succeeded in finding a bootable drive by the time we run out of drives 
in the drive queue, start again at the top of this list. 


The boot code remembers non-ejectable drives (from which it has failed to boot) as bits in a word. 
This means that drive numbers should be in the range 1..15 (because of built-in drivers, SCSI 
drivers should start looking for free drive numbers at drive number 5; see the note in the source). 


Before running through all SCSI devices, the SCSIBoot code issues a SCSIReset call to reset the 
SCSI bus. However, some (newer) SCSI conrrollers go into a “unit attention” state upon reset; 
because the ROM expects to be able to read from the device immediately after reset, any such 
device cannot be a Macintosh Plus startup volume (because the SCSIBoot code would not be able 
to successfully read the boot blocks from it). Use controllers without this “unit attention” feature 
with Macintosh Plus. 


It does no good to post a disk-inserted event for an SCSI drive at driver-install ome; the ROM will 
try to boot from your drive if it finds your drive in the drive queue. In fact, any drive it doesn't 
boot from is forgotten, so we have to pull a few special tricks to “remind” the system if our drive 
isn't bootable (again, refer to the source). 


The first drive found (in the drive queue) with a System file and Finder is used as the startup 
volume. Once mounted, an SCSI-based volume looks like any other volume to the system, and no 
special handling is needed. 


If no bootable drive is found on the first pass through the drive queue, the boot code starts over 
with SCSIBoot (which means that the SCSI bus may be reset again after your device's driver has 
been loaded!). 


king v Lv 
You must place your driver on your hard disk for it to be bootable. If your drive cannot be read 
(by the ROM's generic read routines) immediately after the SCSI bus is reset, then it cannot be 
bootable (this is the case with most controllers which support “unit attention”, described above). 


The SCSI Manager chapter of Inside Macintosh Volume IV contains descriptions of the tables on 
blocks O and 1 of a bootable SCSI device (equates for these tables are now in the Software 
Supplement equate files). These tables were designed to allow several CPUs’ operating systems to 
own their own partitions on a drive; if you only support one operating system (Macintosh HFS), 
your drive will look something like this (the size of your driver may be different): 
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Block O: Block 1: Blocks 2 thru 5: 
Driver Descriptor Map Vi tion M the Driver 


Signature: $4552 (always) Signature: $5453 (always) 
Block Size: $0200 First Partition: 

Block Count: SXXXXXXXX Starting Block: $00000006 
Device Type: $0000 Size: SXXXXXXXX 


Blocks 6 thru X: 
the Partition 


Device ID: $0000 FS ID: TFS t' (for Mac) 
Data Start: $00000000 Next Partition: 

Driver Count: $0001 Starting Block: $00000000 
First Driver: Size: $00000000 

Starting block: $00000002 FS ID: $00000000 

Size: $0004 

CPU Type: $0001 (Mac) 





The utility which you distmbute with your drive should do (at least) the following, to prepare a 
drive for use as a Macintosh blocked volume: 


¢ Take care of any low-level formatting required by the drive (perhaps reading defect maps 
from files on a floppy dismbuted with the dnve). 


* Setup and write out the Driver Descriptor Map, the Device Parution Map, and the driver, 
so that the system will be able to boot from the device. 


e Open the driver from floppy (you must simulate the process that the system uses at boot 
time), then call DIZero to ininalize the partition as a volume. 


Your utility should also take care of any routine maintenance, such as partition management (if 
you decide to support multiple partitions or operating systems), driver updating, mounting of a 
drive after boot time, etc. 


The sample driver contains functionality to support an installation utility; this way, the driver can 
be used by the utility to write itself (as well as the DDM and DPM) out to the newly formatted 
disk. 


A utility can install the sample driver by JSRing to the driver code; the first instruction is a branch 
to the install routine within the driver (the driver cannot be a DRVR' resource because of this 
branch instruction). After the install routine has been called, your utility will need to post a 
disk-inserted event for the drive whose drive queue element was created by the install routine 
(your utility can find this at an “agreed-upon” location in the driver's globals). 


Building the software 


The example driver was written using a pre-release version of the Macintosh Programmer's 
Workshop Assembler, part of Apple’s new Macintosh-based development environment. If you 
use a different assembler, you will probably have to change some of the source files (mainly the 
pseudo-opcodes and macro calls). MPW is not yet available as of this writing; please do not call 
us to ask for it (the conversions to other currently-available development environments are not 
difficult!). 


This driver requires the SCSI equates source file, included in this Supplement. 


Known bugs 
There are a few known problems with this software (if you find more, please write and let us 


know, at the above address). 
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¢ SCSI error handling should be improved. Currently, after an error is detected, the SCSI 
manager calls SCSIComplete to clean up the bus, then returns IOErr. It should request 
sense status from the drive, and handle errors appropriately. 


© The Install code is a large percentage of the driver code, and the memory it occupies could 
be purged after installation time by resizing the memory block that the code resides in, or 
by keeping the actual driver as a separate area on the disk, and having the install code load 
it in separately. 


sj IN -86 v 
Here's a summary of the changes made since the last version; if that version influenced your 
driver, you should make sure you didn't copy my mistakes! 


Thanks to all of you who reported these bugs: 


« The hard-coded value for the new . GetTrapAddress call in SetBlindOK was incorrect (let 
this be a lesson in using equated values!). 


« Also in SetBlindOK, a CLR.W instruction was used to clear TickleFlag (a byte value). 


- My driver source, my documentation, and the alpha draft of the SCSI Manager chapter of 
Inside Macintosh Volume IV differed on the proper value for the signature word for one 
of the device tables; the driver was correct. 


« The first version of this driver contained support for both 256- and 512-byte physical 
sectors. This was interesting as a feature, but made the example cloudy (and besides, 
most popular controllers can be configured for 512-byte sectors). In removing this feature 
at the last minute, I incorrectly recoded an instruction in setting up the transfer information 
block for the transfer (in the routine DiskPrime); rather than moving the sector size into 
the low word of the scNolnc instruction, I did a long move into the low word (a bad 


booboo). 


- In my own hacked-up installer, I used the driver to write itself onto the SCSI device after 
formatting. Since the device I was accessing didn't have a volume mounted (and since the 
area I was writing wasn't within the partition anyway!), I added a special control call. 
Later, I changed the installer to no longer need this control call. At some point after that, I 
had to retype a large section of code from a listing, and made a typo in a register reference 
(in DoSCSICmd). 


* In converting to the “real” SCSI equates file, several labels had to be changed (for 


instance, in the driver globals, SCSICmd [the SCSI command block] was changed to 
SCmd to avoid a conflict). 
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Patches to the SCSI Manager in Macintosh Plus 


There are a number of bugs in the ROM version of the Macintosh Plus SCSI Manager; these bugs 
have been fixed by patching the . SCSlDispatch trap in RAM. 


A number of developers received a file (variously called "SCSI Helper", "SCSI Items”, or 
"Preliminary SCSI Helper”) containing these patches (this file was included in the 26 March 1986 
release of this package). 


The newest System file (version 3.2, included in this Software Supplement) contains these patches, 
so the SCSI Helper file is no longer necessary; in fact, since the patches in the System file would 
be replaced by the [outdated] SCSI Helper patches, it would be a good idea to throw away any 
versions of SCSI Helper you may have. 


Furthermore, you should tell your users to always use this System file (or a more recent one) with 
your SCSI products. 


About the fixes 


These patches fix several problems in the Macintosh Plus ROM implementation of the SCSI 
Manager: 


e Blind writes ( SCSIWBlind) were known to fail on most SCSI controllers. They may stl fail 
— test them on your controller carefully. Note that blind transfers should only be used when 
transferring disk blocks (ie, not when transferring the data for a Mode Select command, for 
instance) because your controller may not be able to keep up the transfer rate if it's 
interpreting the data as it receives it (as it may when transferring non-disk-block data). 


e Blind reads (_SCSIRBlind) were known to fail on a few controllers. They should now work 
for all controllers. See note above about blind transfers in general. 


e A bug in the ROM version of SCSiStat (the routine which returned the NCR chip's status 
byte) prevented it from ever working. SCSTHelper contains a fixed version. 


Your driver must test for the presence of the patches at runtime; furthermore, you must be able to 
boot from your device without benefit of the patches (because, of course, they're not going to be 
loaded until after the System has been loaded). You should also be able to run properly (even if 
slowly, without blind transfers) if the patches are not present, in case the user happens to boot from 
a non-3.2 System. 


To test for the presence of the patch at runtime, you should add a flag to your driver's (DCtiStorage) 
local variables (call it BlindOK), and add the following code to your driver's Open routne: 


;Initialize the “blind-transfer" flag in our globais, 
sand set us up for a NeedTime call after we've finished booting. 
; (assumes that a pointer to our globals is in AQ, and a pointer 
Sto our DCE is in Al) 

MOVE.L Ai,-(SP) ; (save Al across call) 


BSR SetBlincOK jset up the BlindOK flag 
MOVE.L {52} +,AL ; (restore Al) 
BEQ.S G1 ;all patched! 
MOVE.W #1,DCtlDelay({Al) jwe'll need time later -- 


BSET #dNeedTime, DCtiFlags (Al) ;flag it 


Your driver's Control routine will eventually get an accRun call (CSCode = accRun). This will 
happen as soon as the first application calls SystemTask. When this happens, BsR to the following 
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routine (before exiting through !ODone in the normal manner): 


:We've gotten an accRun call. Check to see if it's OK to do blind 
stransfers now, then reset the dNeedTime flag in our DCE, 

> (assumes that a pointer to our globals is in AO, and a pointer 
zto our DCE is in Al). 


GotNeedTime 
CLR.W DCtlDelay (Al) ;we don't need time anymore 
BCLR #dNeedTime,DCtlFlags(Al) ;unflag it 
BSR SetBlindok ;re-set up the BlindOK flag 
RTS 


The following routine checks to see if it's OK to do blind transfers; place it somewhere in your 
driver (it's called from the added Open and Control routines above): 


;Set up the "blind-transfer" flag in our globals, based on ROM 
;version and patch state of the SCSIDispatch trap. (This check 
“for ROM version only applies here -- do not use it for general 
;version checking). 


: (This routine assumes that a pointer to our globals is in A0) 


SetBlindOK MOVE.L A3,-(SP) ;save A3 
MOVE.L A0,A3 ;keep globals ptr here 
CLR.B BlindOK(A3) pdetault co TROC OK!” 
MOVE.L ROMSase,A0 ;get pointer to ROM start 
MOVE.W 8(A0),DO ;get ROM version word 
CMP .W #$0075,D0 zare we newer than MacPlus? 
BNE.S 41 ;yes! Make blind xfers OK. 
we're running on Macintosh Plus ROMS -- has _SCSIDispatcn 


;been patched in RAM? (Since _SCSIDispatch is a new trap, we 
shave to use the new flavor of GetTrapAddress). 

;Note: The last version of this example had the GetTrapaAddzress 
;trap incorrect: the correct version is shown. 

MOVE.W #5A815,D0 get a SCSIDispatch trap word 
DC.W $A346 _GetTrapAddress for new OS 
CMPA.L ROMBase, AQ is it below ROMbase? 

BGE.S @2 no: Unpatched, so no blinds. 


we =, NO “a 


:Either the ROMs are newer than Macintosh Plus's, or we've patched 
; SCSIDispatch in RAM. Either way, blind transfers should be OK now. 
Qi ST BlindOK (A3) 


Either we just made blind transfers OK, or it's not OK to use them. 


Q@2 MOVE.L (SP)+,A3 ;restore A3 
TST.B BlindOK(A3) ;set CCR flags 
RTS sand exit. 


Anytime you use _SCSIRBlind to transfer disk block data, test the flag; if it's clear, use SCSIRead 
instead (the same goes for _SCSiWBlind if you are using it). 
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Introduction 


This document describes the major changes made in the system file and the 
LaserWriter driver between the System Software version 2.0 and the System 
Software version 5.0 release. 


System File 4.2 
Font Manager 


There is a new font manager that is now backpatched for the Macintosh 
Plus. 


Palette Manager 


Fixed problem with InitGraf. The device list is built after the first InitGraf, 
and all devices in the list are marked inactive. INIT31 now includes an 
additional InitGraf. This way InitPalettes sees more than just the defautt 
device. 


The procedure CopyPalette is now implemented. Its Pascal declaration is 
as follows: 


PROCEDURE CopyPalette(srcPalette,dstPalette: PaletteHandle; srcEntry,dstEntry, 
dstLength: INTEGER); INLINE $AAA1; 


Note: a palette may not be copied to itself. If srcEntry+dstLength exceeds 
the size of the source, dstLength is trimmed. If dstEntry+dstLength exceeds 
the destination, the handle is resized and cleared to make room for the new 
entries. 


ADB 


Changed mouse button debounce time back to 20 milliseconds, and 
changed code so that mouse downs always get noticed. Will now never 
discard a down/up pair, only up/down pairs. 


Sound Manager 


The sound manager VBL problem is fixed. The sound driver uses low 
memory as a vbi queue element. The sound vb! queue element is now 
forced to be the last one in the queue, fixing a bug which caused the 
machine to hang. On older versions, if the sound is active the low memory 
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queue is zeroed whether there is another element in the queue or not; this 
used to cause the machine to hang. 


Sound Manager uses soundactive diff sound driver, thus soundactive 
could be true with no task installed. We now check for an error from 
VRemove. 


INIT31 


INIT 31 guarantees 216K of systen heap for each INIT. The first initWindow 
causes a Cail to InitPalettes, which can take up a couple of K, depending on 
screen configuration. This was causing the first INIT to suffer. This patch 
places the InitPalettes in INIT31, prior to the first INIT's execution. The patch 
to call InitPalettes fron InitWindows is superfluous and has been removed. 


Added some code to perform InitPalettes on any Macintosh with the low 
memory global ROM85 set to $3FFF or less. 


Menu Manager 


Enable Bits. When there are more than 31 items in a menu and one of the 
items is disabled, the disabled item would sometimes "float". That is, it 
would move from item to item, and disable the one it landed on. This has 
been fixed. 


Hierarchical menu and scrolling arrows do not resize if the menu font size 
changes. 


HiliteMenu is patched to handle situations where the low memory global 
mBarHeight = 0 and Menukey is called. When HiliteMenu was attempting to 
get a huge handle to save the bits behind the title, it would blow up in the 
process. Now if mBarHeight < 2 and MenukKey is called, it does nothing. 


Fixed InsertEnableBit for Mac Plus, SE and Mac Il for hierarchical menus. 
Fixed MDefProc so that popup menus appear even when passed popupitem 
=0. PopupMenuSelect recognizes popupitem = 0; when PopUpitem = 0 the 
top of the menu item is pinned at the parameters top/left. 


Script Manager 


mBarHeight is now checked for a 0 value, for use when switching in and 
out of applications which hide the menubar. 


The Script Interface System is initialized with an InitWindows call BEFORE 
a launch to take care of programs requiring text input before the first launch. 


Fixed FindWord so a sequence of blank spaces which include a carmage 
return no longer act as a single word for selection and word wrap. 


Non-breaking spaces didn't always work; now they do. 


ShutDown Manager 


Changed UnMountVol to unconditionally close all open files on the target 
volume if bit 9 is set in the trap word. This is an enhancement intended for 
use only in situations such as shutdown where the volume must first be 
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unmounted. In general, applications should use UnMountVol WITHOUT the 
bit 9 set, which returns a file busy error (fBysErr) if there are any open files 
on the volume. 


Monitors (cdev) 


ActivatePalette is now called when the bit depth changes. This prevents 
double updates in some applications, and takes care of inaccuracies in the 
color environment which persisted until the next call to the Palette Manager. 


The Monitors cdev is vulnerable to other program's sloppiness in handling 
ports. To change the bit depth, Monitors must scan the portlist which Color 
QuickDraw maintains in low memory. If applications fail to call ClosePort 
before disposing of a grafport's memory, or allocate a memory for the port in 
such a way that it can move between the calls to OpenPort and ClosePort, 
an invalid port is left on the portlist. The next time the portlist is scanned, 
which may be much later, various sorts of mayhem result (usually a bus or 
address error). Monitors and the Palette Manager are the only ones that 
scan (or should 


The Monitors control pane! cdev does not expect any video card to have 
different screen sizes in different modes (for different bit depths). 
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ROM Patches 


QuickDraw 


QuickDraw now only calls color mapping CopyBits code whenever the 
color table seed of the source PixMap differs from that of the destination 
PixMap. This gives a noticeable performance increase when dealing with 
PixMaps. 

SetCursor 

In some applications, SetCursor used to trash register A2 which resulted in 
crashes, particularly with multiple screens. This has been fixed. 
Miscellaneous Fixes 


Switch-launching between floppy disks on a Mac Il with multiple monitors 
could crash. This has been fixed. 
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The MultiFinder Development Package has the following contents: 


¢ The document Are You MultiFinder Friendly? 

¢ The document How to Write a Background Application. 

* The document MultiFinder Documentation Errata. 

e The document Questions Frequently Asked About MultiFinder. 
_ e The document A Note About Sublaunching. 

e The disk MultiFinder Interfaces. 


—— 
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What is different about MultiFinder? 
introduction 


MultiFinder 1.0 is a set of operating system functions that has been 
added to the Macintosh with minimal impact on the programming model. The 
additional functionality provided by MultiFinder is essentially the ability to run 
multiple applications on the Macintosh, all of them sharing the same screen. 
Great care has been taken to introduce this new functionality without altering 
the familiar Macintosh environment to the point where none of the Macintosh 
applications presently available could run. 


There are certain programming actions and assumptions made by some 
Macintosh applications that have not caused problems in the current Mac 
environment, but may have drawbacks under MultiFinder 1.0. These drawbacks 
can range from mild to serious. To be truly “MultiFinder friendly” means that an 
application will have to avoid all of these pitfalis. 


This document is intended to serve as a brief guide for Macintosh 
knowledgeable programmers who want to make their applications MultiFinder 
friendly. It describes the details of what can and cannot be done under 
MultiFinder. A list of do's and don'ts is given, and they generally fall into one of 
two categories: now and future. Those in the now category are generally things 
which cannot be done with even today's MultiFinder. Those in the future 
category are things which will work with today’s MultiFinder, but it is evident to 
us that in the future, such behaviour will break. Therefore, now may be the time 
to start thinking about avoiding these things. 


The Salient Differences 


Applications now must be aware that they can be executing alongside 
others in the Macintosh; they cannot presume they have complete contro! of the 
machine. This is nothing new for applications that are compatible with Switcher. 
(In fact, the environmental differances between Switcher and MultiFinder are 
minimal.) This means, for example, that MemTop is used to give the physical 
size of your application heap, not the physical size of the machine. Of course, 


your application shouldn't rely on MemTop at all. Do not rely on the relative 
location of your heap to the system heap or presume your heap is of a particular 
size. Checking the error results from Memory Manager allocation traps is 
always a gocd idea. 


The shared use of the screen is arbitrated by the Layer Manager. The 
Layer Manager software is not directly called by any applications; rather, it is 
called by various existing Window Manager routines when necessary. 
Applications that interact with the Window Manager in a resonable manner 
(described below) can be assured that they will be compatible with MultiFinder. 


As MultiFinder schedules the CPU amongst the various applications, 
most of the low memory contents are switched. This implies that at any given 
time the contents of low memory can belong to any of the currently running. 
applications. This further implies that at interrupt time, the contents of low 
memory do not necessarily belong to any particular application, and very 
possibly not to the application that “owns” the interrupt handler. Therefore, 
portions of an application that might be invoked asynchronously, such as VBL 
handlers in the system heap, interrupt handlers, and so forth, can no longer 
presume that various portions of low memory or the CPU register set contain the 
values expected. 


Genera! Hints 


Here is a list of do's and don'ts based on problems that have been 
observed in current Macintosh applications. 


« If you are patching traps, use the SetTrapAddress() calls rather than 
writing into the dispatch table in low memory. Place your patch receiving 
routines in your application heap and not in the System Heap. Unplug all of 
your patched traps before exiting your application. Under the MuttiFinder, any 
patches an application makes to a trap apply only to the application that 
patched the trap. In other words, if you are running alongside MS-Excel, your 
patches affect only you, and not MS-Excel. (NOW) 


* Do not assume that the value of A5 is correct when a trap is made. This 
means that if you patch a trap, and the code you install references your 
application’s global data, you must manually save AS, set it to CURRENTAS, do 
your stuff, and restore the original AS when you are done. Note that the 
Quickdraw globals will always be pointed to by AS, it's just that AS may not point 
to your global data segment. (NOW) 


+ Do not attempt to access an application's global data from within an 
interrupt handler. It is not safe to presume that CURRENTAS even contains the 
correct value. Recall that certain traps are callable from interrupt level, and if 
you patch those traps, the patch code must pretend it is called at interrupt level 
as well. (NOW) 


Most IO completion routines (for asynchronous IO) run at interrupt level. 
The above paragraph implies that your provided IO completion routines cannot 
access your global data, or at least not without carrying the A5 value around 
within the code segment. Applications which currently rely on AS being 
available in the low memory location CURRENTAS at IO completion time will not 
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function properly with MultiFinder 1.0. (Asynchronous file system operations will 
work correctly; only device manager and sound completion routines need to 
carry their A5 values.) 


© + VBL tasks (whose receiver addresses are in the application heap) only 
run if the creating application is frontmost. VBL tasks that are in the System 
Heap run all the time, but as in the case of interrupt routines, absolutely no low 
memory context can be guaranteed. (NOW) 


¢ Much of the MultiFinder's functionality depends on using the Apple 
menu in novel ways. MultiFinder likes to therefore presume that it owns menu 
data structures of the Apple menu. Enabling and disabling of items should be 
done through traps provided for that purpose; direct manipulation of data 
structures should be avoided. (FUTURE) 


-e The less your application accesses low memory, the better. Writing to 
low memory, however, is much more objectionable than reading, and shouid be 
avoided like the plague. in the long run, low memory will disappear, so writing 
an application which doesn't depend on it is a noble goal. (FUTURE) 


- Do not assume that exit time (that happy time just before you get around 
to calling ExitToShell()) is lawless because you think the application heap and 
screen’s days are numbered. Short cuts to clear the screen (for example 
PaintRgn(GRAYRGN, DESKPAT) or a second call to InitWindows()) are not 
allowable. Do not destroy fields in system data structures, like the WindowList, 
before you exit. (NOW) 


* Try not to use the low memory notification procedures unless (8.9. 
IAZNotify, EjectNotify, etc.) absolutely necessary. Someday there will be a 
supportable mechanism to communicate such events to the application. We will 
attempt to support these as long as is rationally possible, but someday... 
(FUTURE) 


- Someday, the Macintosh will expect applications to run in the 680X0 
user mode (as opposed to today’s supervisor mode), so in anticipation of that 
great day, avoid using any of the 680X0 privileged instructions. (FUTURE) 


. Interact with the desk scrap by using the Scrap Manager whenever 
possible; avoid maniuplating either the low memory Scrap Manager data 
structures or the Clipboard file itself directly. 


Perhaps the most intrusive aspect of MultiFinder is its commandeering of 
the Window Manager and the Event Manager. Therefore, it is most sensitive to 
less than orthodox interactions with these Managers on the part of the 
application. 


Window Manager 


With regards to the Window Manager, proper functioning under 
MultiFinder requires attention to some basic guidelines; applications already 
respect most of these. 


- The Window Manager data structures are owned by the Window 
Manager, and should never be modified directly by an application. This 
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includes all of the low memory values defined by the Window Manager, in 
addition to any of the fields (including the GrafPort fields) contained in the 
window record itself. Because of the robustness of the procedural interface to 
the Window Manager, this is rarely done, but beware nonetheless. (Off-screen 
GrafPorts are yours to do with as you please.) (NOW) 


¢ All drawing to the screen should be done within the bounds of a window 
with the appropriate QuickDraw calls. This means that applications should not 
write directly to screen memory. Always draw into GrafPorts that your 
application has created. (NOW) 


e Don't try to circumvent the Window Manager itself. Some clever 
applications save the bits from the Window Manager port under a dialog they 
may have just put up. When the application disposes of the dialog, it recopies 
the saved bits back into the Window Manager port, subsequently ignoring the 
update events for those windows. This leads to great trouble when the bits 
under the dialog belong to another running and drawing application. Stale bits 
end up being replaced on the screen. (NOW) 


¢ The Window Manager port is generally off limits. It belongs strictly to the 
Window Manager. Yes, this means that applications cannot draw on the 
desktop! Consider the call GetWMGRPort() to be for amusement-only and 
certainly read-only purposes. The fabled DESKHOOK, a low memory vector 
which allowed applications to draw on the desktop, has been eliminated. 
Applications that use DESKHOOK will not function as expected. (FUTURE) 


* The visRgn field of the GrafPort in the window record is the foundation 
of the Layer Manager. Do not touch this region for any reason. (NOW) 


Event Manager 


The Event Manager has also been modified extensively. The important 
thing to remember is that update events are serious. When an application is 
running in the foreground, events are fed to it as usual. When an application is 
not in the foreground, however, it is switched in whenever an update is required 
in one of its windows. MultiFinder feeds update events to the application when it 
calls GetNextEvent(). MultiFinder will continue to feed the update events to the 
application until it actually processes them. This implies that applications are 
discouraged from implementing deferred update event processing 
mechanisms, and should respond (that is, draw) as a direct response to 
receiving the update event. In general, if you are calling GetNextEvent(), you 
should be prepared to receive and respond to update events. 


+ NULL events should also be treated a bit more carefully under 
MultiFinder. NULL events are dispensed with less regularity, and are intended 
to be used for cursor tracking. Periodic garbage collection and other similar time 
consuming actions should not be performed on every NULL event received. 
(NOW) 


A better suggestion is to examine the TickCount() function and only 
perform garbage collection activities every so often. If the alotted time has not 
elapsed since the last garbage round, do nothing at NULL event time and call 
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GetNextEvent() immediately. Doing so helps maintain a reasonable degree of 
performance with our ersatz multitasking system. 


* Don't feel compelled to cali SystemTask() on every NULL event. Call 
GetNextEvent() instead. It will take care of the functions previously monitored by 
SystemTask(). (NOW) 


¢ Try to support the Suspend/Resume events. If you do, you can 
differentiate between scrap coercion and proper desk accessory activity. This 
will allow you to react to desk accessories more intelligently. MPW, for example, 
unloads many code segments before calling OpenDeskAcc(). In most cases it is 
just the scrap coercion that is necessary before a switch. Besides, 75% of the 
time required for a switch is for scrap coercion; all of this time can be eliminated 
if Suspend/Resume events are supported. See Part lil. (NOW) 


e Be sure to support the appropriate keyboard equivalents for menu 
editing commands (for example, Command-C, Command-X, Command-V). 
(NOW) 


Memory Manager 


. Don't make assumptions about the memory model concerning the 
juxtaposition of the various heaps. The System Heap is not necessarily 
adjacent to the Application Heap. (NOW) 


* The size of your heap is given only by APPLZONE->bkLim. The extent 
of possible heap growth can be seen by calling GetAppiLimit(). (NOW) 


e You can see the size of your stack by calling StackSize(). We are trying 
to think of a reasonable new way of resizing your stack; in the meantime, calls to 
SetAppiLimit() will have to continue to suffice. (NOW) 


« Additional heaps, if required, should be allocated within your origina! 
heap as non-relocatable blocks. If you must, build them on the stack, but please, 
nowhere else. in other words, your available and usable memory should be 
considered to be your application heap and your stack; nowhere outside those 
two ranges. (NOW) 


« Do not presume you know into which heap resources are loaded if they 
did not come from a resource file you apened directly. Resources loaded from 
the system resource file (and printer resource files)-can be loaded into a 
number of different heaps that MultiFinder will allocate dynamically. (NOW) 


e Try to use MultiFinder's temporary block allocation calls for those 
requirements that are large and temporary. For example, if you need a 400K 
copy buffer only once in your application, and only for a short time, have 
MultiFinder allocate it for you dynamically. The space will not be in your heap, 
and as a result, your required heap size can be computed ignoring the 
anomalous requirement, and your application will be much more space 
efficient. Details on how to call this routine are forthcoming. See Part ll. (NOW) 


- Use your friendly (SIZE -1) size resource. This resource is a small 
structure that describes an application's memory requirements. A preferred and 
a minimum size are given; the minimum size should be sufficient for the 
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maximum size should be no larger 


application to behave reasonably well. The 
ferred size of 2 Mbytes is not 


than the application can effectively use; a pre 
sociable. See Part ill. (NOW) 
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New System Functions 


A number of new system functions are available to applications which 
are running under MultiFinder. Some provide new functionality, such as the 
temporary memory allocation calls, while others (8.9. WaitNextEvent) enhance 
existing Toolbox calls. 


WaitNextEvent 


In an effort to reduce the difficulties associated with our polling event 
model, there is a new Event Manager call, WaitNextEvent, that allows an 
application to fit in much more easily. The new call allows the caller to specify, 
in addition to an event record and mask, a time value (in ticks) for which to 
relinquish the processor if no events are pending, and a region that describes 
the current cursor position. 


The time value allows the application to delegate the task of periodic 
scheduling of garbage collection operations to the Event Manager. Given that 
no real events occur in the meantime, the Event Manager does not retum to the 
calling application until the specified time has elapsed. A time value of zero 
causes the Event Manager to return immediately, after providing some CPU 
time to the other processes in the system. When the time value elapses, 
MultiFinder returns a NULL event, with a return value of FALSE. If a “real” event 
occurs before the time value elapses, the event will be returned with a retum 
value of TRUE. 


The region describing the current mouse position should slightly relieve 
the application from worrying about cursor tracking. The application will receive 
a “mouse-moved” event only when the mouse strays outside of the given 
region. The application can then define the region in which the current cursor 
shape should remain the same. When it receives the “mouse-moved” event, it 
can change the cursor shape, recompute the new region for this cursor shape, 
and call GetNextEvent(). The region is given in the local coordinates of the 
frontmost window. More detail on a «mouse-moved” event to follow. 


Ot course, if the calling task is trontmost, and the user generates an 
event, it will be returned immediately. 


Given this new cail, the trontmost application on an idle Macintosh need 
not run at all, and ali available CPU time can be allocated to other applications 
(or future background tasks). 


Details on how to make use of this call will De available in the near future. 


The WaitNextEvent function is às follows: 
pascal Boolean WaitNextEvent (ev, em, sleep, mouse) 


EventRecord rev? 
EventMask em; 
unsigned long sleep; 
RgnHandle mouse; 


The trap number for WaitNextEvent is 0xA860. 


lf mouse is NIL, no “mouse-moved” events will be generated. Note that 
an idle Macintosh will generate no “mouse-moved” events as well. 
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Temporary Memory Allocation 


In order to reduce the memory requirements of an application’s heap, 
MultiFinder provides a set of temporary memory allocation services which can 
be used for large, transient memory requirements. The SIZE resource of an 
application need not reflect, therefore, these bret and occasional requirements, 
which serves to improve the memory efficiency of the system as a whole. 


It is important to remember two things when using this memory: first, de 
sure to release the blocks of memory as soon as possible to allow other 
applications to use some, and to allow the user to launch new applications. 
Secondly, never structure your application such that it depends on the 
availability of any of this temporary memory. This means having a backup plan 
in place should no temporary memory be available, most likely reserving an 
emergency amount of memory within your heap zone to complete the common 
procedures. 


For example, the Finder now uses these temporary memory calls to 
secure copy buffer space to be used during file copy operations. Any available 
(unused by running applications) memory is dedicated to this purpose. The 
Finder releases the memory as soon as the copy is completed, making the 
memory available again to other applications, or to the MultiFinder for launching 
new applications. 


if the Finder cannot allocate this large temporary copy buffer, it wilt- - 
perform the copy using a reserved small copy buffer from within its own heap 
zone. This is clearly more desirable than refusing to copy (or worse yet, 
crashing) because no temporary memory was available. 


The procedural interface for the temporary memory allocation service is 
given below. 


FUNCTION MFMaxMem (VAR grow:Size) : Size; 


Compacts the muttifinder heap zone, purges all purgeable blocks and 
returns the number of bytes of the largest contiguous free block for tamporary 
allocation. 


FUNCTION MFFreeMem :longint; 


Returns the total amount of free memory available for temporary 
allocation, in bytes. 


FUNCTION MF TempNewHandle (logicalSize:Size; VAR resultCode:OSErr) 
Handle; 


Attempts to allocate a new relocatable block of logicalSize bytes for 
temporary usage and return a handle to it. The new block will be unlocked and 
unpurgeable. If an error occurs, MFTempNewHandle will return a nil handle. 


‘Result codes noErr No error 
memFullErr Not enough room. 
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PROCEDURE MFTempHLock (h:Handle; VAR resultCode:OSErr); 


Locks the specified relocatable block, preventing it from being moved 
within the MultiFinder heap zone. 


Result codes noEr No error. 
niiHandie Err Nil master pointer 
memWZErr Attempt to operate on a free block. 


PROCEDURE MFTempHUnLock (h: Handle; VAR resultCode:OSErr) ; 
Unlock the specified relocatable block, allawing it to move. 


Result codes noErr No error 
nilHkandieEr Nil master pointer. 
memWZErr Attempt to operate on a free block. 


PROCEDURE MF TempDisposHandle(h:Handle; VAR resultCode:OSErr) ; 
Release the memory occupied by the relocatable block whose handie is 


Result codes noErr No error. 
memWZErr Attempt to operate on a free block 


interface files for these services will be forthcoming. Note that these 
interface definitions may change. 
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inclusion of a SIZE Resource 


To be truly MultiFinder friendly, an application must include a SIZE 
resource. Made popular in the Switcher era, the SIZE resource provides a 
mechanism by which an application can make known its anticipated memory 
raquirements. Additionally, bits in a flags word are used to indicate varying 
degrees of MuitiFinder compatibility. 


When an application is launched under MultiFinder, it is placed into a 
memory partition of a fixed size. Of course, different applications will have 
dramatically different memory requirements. it is the application’s responsibility 
to inform MultiFinder just how large a memory partition it will require. This 
information is contained in the SIZE resource in the form of a preferred size and 
minimum size. 


The preferred size is the amount of space which the MultiFinder attempts 
to secure upon launch; if it is unavailable, the application is placed into the 
largest contiguous block available providing that it is larger than the specified 
minimum size. The user, through the Finders Getinfo dialog, can modify the 
preferred size of an application. An application which does not supply a SIZE 
resource is launched into the default partition size of 512K. 


The format of a SIZE resource is given below: 


struct { unsigned short flags; 
unsigned long pref size; 
unsigned long min size; 


1; 
The meanings of the bits in the flags word are: 


Bit Meaning 

15 Reserved 

14 Understands Suspend-Resume event 
13 Reserved 

12 Understands background NULL events 
11 MultiFinder Aware 

10-0 Reserved 


If an application understands Suspend-Resume events, the charade of 
scrap coercion is not played for the application when it is being switched to or 
from being the topmost application. Therefore, an application which keeps local 
scrap can convert to and from global scrap when being switched. Additionally, 
the application can monitor its “topmost” status by watching the passage of 
Suspend-Resume events. 


lf an application indicates that it understands background null events, it 
will continue to receive null events even if it is not the "topmost" application. This 
is the mechanism by which CPU time is distributed in MultiFinder's cooperative 
multitasking environment. For more information, see the section about writing a 
background application. 


An application indicating that it is MultiFinder aware makes the promise 
that it abides by the guidelines for being MultiFinder friendly. Additionally, event 
traffic at application switching time is minimised because the application is 
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presumed to deactivate its topmost window at suspend time, and reactivate the 
window at resume time. MultiFinder does not generate the deactivate-activate 
pair of events for the application if the MultiFinder aware bit is set. 


Creating Your SIZE Resource 


There is no simple formula for finding the appropriate size requirement 
for all applications. There are so many factors affecting memory requirements, 
that only general guidelines are useful. 


An application's memory requirement is comprised of a number of parts. 
These are: static heap, dynamic heap, A5 world, and stack. The static heap size 
includes objects which are ever present during the course of execution of the 
application. These could be code segments, toolbox data structures for window 
records, etc. Dynamic heap requirements come from various heap objects 
created on a per document basis (which may vary in size proportionately with 
the document itself), and objects which are required for specific commands or 
functions. The AS world is a static object that exists outside of the bounds of the 
application heap, the size of which depends on the amount of global data and 
inter-segment mingling the application has. The stack, of course, is the stack. 


An application's writer has the best knowledge of the expected memory 
requirements of the application. Macsbug and its heap exploring commands 
can be quite a help in empirically determining the applications appetite for 
memory. Snooping around in the application’s heap at key times while 
performing all of the application's functions would be quite educational. 


The minimum size should be chosen such that the application would 
never “system error’ if required to run in this amount of memory. Some 
application writers may choose to specify as minimum the amount of memory 
required merely to bring up an "I don't have enough memory” dialog. Others 
may choose to use the minimum useful amount of memory here. 


The preferred size should be chosen to allow the application to perform 
90% of its function without problems. On the other hand, it shouldn't be too 
greedy. Remember that in the MultiFinder environment that applications are 
sharing the machine with one another, and an application with a 1024K 
preferred size is likely to be viewed with contempt by users and other 
application writers alike. 


The SIZE resource is of type "SIZE" and ID (-1). MPW tool Rez will 
provide a modified types.r file for the new flag bit definitions. 
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Introduction 


This document is intended to outline the issues in writing a successful 
background application for MultiFinder. The release of MultiFinder 1.0 will 
constitute the first step on the path to a true multi-tasking Macintosh operating 
system. This release of MultiFinder will not significantly change the programming 
model for the current set of applications; it will however, support a limited form of 
background processing. 


This document is intended to serve as a brief guide for the Macintosh 
knowledgeable programmer. Any reader of this document is assumed to have 
already read Are You MultiFinder Friendly ?. 


Programming Model For Background Processing 


MultiFinder is a set of operating system functions which has been added to 
the Macintosh with minimal impact on the programming model for existing 
applications, most of which run without changes within the MultiFinder 
environment. 


With the advent of multiple applications on the screen, screen consistency is 
needed across applications. MultiFinder groups application windows in “layers”. 
Only the front-most layer is active and receives the users events (@.g. mouse 
up/down, keys, etc). When a user wishes to interact with an application, he clicks 


on one of the windows of an application and brings that layer (and all of the 
windows in the layer) to the front. 


Applications which are not front-most will not receive user events, but only 
update events when a foreground window changes make them necessary. 
MultiFinder friendly background tasks can arrange to receive periodic null events 
during which they can perform background functions. 


MultiFinder supports a new class of application called a “background” task. 
A background task is an otherwise normal application that uses null event 
processing time to preform some useful background function. The Finder, for 
example now takes background time to keep the desktop consistent (disk inserts, 
files being added or removed, etc). 


In MultiFinder, the programming model for background tasks is somewhat 
constrained as arbitrary preemption is not provided. Unless the functionality of 


your application would benefit greatly from background processing, it # 
recommended that you wait until subsequent releases of MultiFinder that will 
provide a complete preemptive model. 


Scheduling 


The look and the very responsive feel is a key strength of the Macintosh. 
The single task nature of the pre-MultiFinder Macintosh has set a very high 
standard of how an application and system should respond to the user. In the 
current model, much of the processing time is spent processing null events. This is 
exactly the processing time that MultiFinder tries to give to the background tasks. 
The definition of a successful background application is one that uses normally 
unused null event processing for effective background work, while not significantly 
affecting the responsive nature of the foreground application. 


Foreground applications are only activated at the user's request. Each time 
any application is scheduled, it runs until it calls GetNextEvent (GNE) or 
WaitNextEvent (WNE see below). Scheduling for a background tasks under 
MuitiFinder is done differently. MuitiFinder schedules a “ready” background task 
when the foreground task has no current events pending and no window updates 
are needed. The foreground application will continue to get null events at regular 
intervals so that cursor tracking and caret blinking can continue. Because 
MultiFinder doesn't support preemptive scheduling, each background task must 
call GNE/WNE at regular intervals (between 50 and 100 milliseconds) so that the 
foreground task can keep its responsive nature. When a background task has 
control, user events destined for the front-most application will not be handled until 
the background task calls GNE/WNE. 


Supporting the responsive nature of the foreground task is a key issue for 
background processing. The foreground task is not required to return the favor to 
the background tasks. Because the foreground task can take ail the time it wants, 
the background task can't be guaranteed any CPU time. 


When a background task comes to the front, it has all the rights and 
privileges of a foreground application. It receives user events and it can use any 
toolbox service (File Manager, QuickDraw, Window Manager, etc) as any other 
active foreground application. Keep in mind that the same task executing in the 
background can also use any toolbox or OS service, but the task won't see user 
events while running in the background. 


WaitNextEvent 


In MultiFinder 1.0, there is a new Event Manager call which will allow an 
application to use the CPU more efficiently. This new cail is named 
"WaitNextEvent" and it helps reduce the null event traffic that an application sees. 
The new call allows the caller to specify, in addition to an event record and mask, a 
time value for which to relinquish the processor if no events are pending, and a 
region which describes the current cursor position. The use of WaitNextEvent will 
eliminate the need for an idle application to waste processing time by continuously 
processing null events. 


The time value (in Ticks) allows an application to “sleep” until a real event 
occurs or the specified time has elapsed. A time value of zero will cause the Event 
Manager to “sleep” the caller indefinitely, or until a real event occurs. Many 


Ao. 
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The SIZE Resource 


MuitiFinder depends upon a resource called the SIZE resaurce. It is 
expected that application developers create and maintain the information in the 
SIZE (-1) resource. The SIZE resource contains information that helps MultiFinder 
effectively manage the application. Most importantly the SIZE resource specifies 
the memory partition required to safely run the application. It also includes flags 
that determine how “MultiFinder Friendly" the application is. The following data 
structure describes the data from the SIZE resource: 


type 'SIZE* í 
boolean dontSaveScreen, /* reserved */ 
saveScreen 
boolean ignoreSuspendResumeEvents, /* suspend-resume */ 
accept SuspendResumeEvent a; 
boolean enableOptionSwitch, /* reserved */ 
disableOptionSwitch; 
boolean cannotBackground, /* accept MultiFinder bkgd */ 
canBackground; 
boolean notMultiFinderAware, 
MultiFinderAvare; /* MultiFinder's new rules */ 
unsigned bitstring[11] = 0; /* reserved */ 
unsigned longiat; /* size */ 
unsigned longint; /* min size - 32k */ 


}3 


Only the Bold items are supported in MultiFinder and all other fields are 
raserved. The other items are included in order to maintain compatibility with 
Switcher which also used a SIZE resource. 


e SuspendResumeEvent - When true, this boolean means that the 
application knows how to process Suspend/Resume events. This is an 
optimization first done in Switcher to reduce the overhead in moving the desk scrap 
from task to task. When true, MultiFinder notifies the application before making it 
inactive and after activating it. In this way, the application knows when to process 
the desk scrap. 


Failure to support this optimization requires MultiFinder to perform an 
elaborate charade to insure that the contents of the Clipboard can be transferred 
from one task to another. This charade visibly slows down the time it takes to 
switch from task to task. Much of this charade is still performed unless the 
MultiFinderAware bit is set. 


When the application calls GNE/WNE, MultiFinder returns a suspend event. 
The application does not become inactive until the next call to GNE/WNE. The 
application converts any local scrap into the standard Macintosh scrap (Clipboard). 


When the application calls GNE/WNE, MultiFinder returns a resume event. 
The application may now convert the global scrap into its own private scrap, if 
necessary. 


Suspend and resume events conform to the standard Macintosh event 
structure. They both have an event code of 15 in the 'what' field, classifying them 
as application-defined events (type app4Evt). 
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The meanings of the bits in the Suspend/Resume event message field are: 


Bit Meaning 
0 O = suspend event 
1 = resume event 
1 1a Clipboard conversion not required 
1 = Clipboard must be updated and converted to ail formats 
2-23 Reserved | 
24-31 High byte value of 01 indicates a suspend or resume event. 


If only SuspenResumeEvent is set and not MultiFinderAware, the application 
will also receive activate and deactivate events as well. 


* MultiFinderAware - When true, this boolean means that the application is 
MultiFinder aware. It follows the dos and don'ts outlined in Are You MultiFinder 
Friendly?. Specifically, this bit tells MultiFinder to minimize the event traffic as 
follows: 


Besides the normal processing of the suspend event, the application can 
take two different actions depending on the front-most window. If the application's 
window is on top, the suspend event should also be treated as though a deactivate 
event was received as well. Specifically, scroll bars should be deactivated. If the 
application receives a suspend event with a desk accessory on top, the application 
will call SystemEvent with a deactivate event. 


Besides the normal processing of the resume event, the application can take 
two different actions depending on the front-most window. If the application's 
window is on top, the resume event should also be treated as though an activate 
event was received as well. Specifically, scroll bars should be activated. Ifthe 
application receives a resume event with a desk accessory on top, the application 
will call SystemEvent with an activate event. i 


In this way, much of the overhead in switching from task to task has been 
removed. In general, if the MultiFinderAware bit is set, the SuspendResumeEvent 
bit should also be set. 


e CanBackground - means this application knows how to take background 
null events and will still support the foreground task. 


« Size - MultiFinder supports only one memory size for an application. 
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Introduction 


This document updates the documents Are You MultiFinder Friendly? 
and How to Write a Background Application. 


WaitNextEvent 


FUNCTION WaitNextEvent (eventMask: Integer; VAR theEvent: 
EventRecord: sleep: longint; mouseRgn: RgnHandle): 
BOOLEAN ; INLINE $A860; 


The documents How to Write a Background Application and Are You 
MultiFinder Friendly that are included in this package are both out of date in 
regard to WaitNextEvent: 


*WaitNextEvent currently expects the coordinates of the mouse region 
to be in global coordinates. 


¢ Passing a 0 in the sleep parameter for WaitNextEvent means that 
your application will give up no ticks at all, which would be just like calling 
GetNextEvent. This will give your application ail the time it can get (and will 
still yield a minimal amount of time to other tasks). 


Mouse-Moved Events 


Mouse-moved events are not received by your application as null events 
as documented in "Guidelines ...." Rather, they are app4Events (just like 
Suspend and Resume). They can be distinguished from Suspend/Resume 
events by looking at the message field of the event record. Mouse-moved 
events will have a SFA in the high byte of this field. The low-three bytes 
currently have no meaning and are reserved by Apple for future expansion. 


Network Events 


Included in this seed package are draft versions of Technica! Notes #132 
and #153 which talk about not using Network Events. The warnings in these 
technotes apply specifically to MultiFinder. 


Here's a C fragment: 


/*trap number of WaitNextEvent*/ 


tdefine WNETrapNum 0x60 
/*trap number of "unimplemented trap"*/ 
§fdefine UnimplTrapNum Ox9F 


{ 


Boolean WNEIsImplemented; 


/*Is WaitNextEvent implemented?*/ 
WNEIsImplemented = NGetTrapAddress (WNETrapNum, ToolTtrap) ‘= 
NGet TrapAddress (OnImpiTrapNum, Tooitrap) ; 
/*Main Event Loop*/ 
if (WNEIsImplemented) 
WaitNextEvent (..); 
else 
{ 
SystemTask(); /* for drivers */ 
GetNextEvent (=); 


} 


This code compares the trap for wNE with the unimplemented trap. 
NGet TrapAddress is used because it adds a little precision to the process. 
Please note that calling NcetTrapAddress does not cause compatibility 
problems with 64K ROMS. When run on those ROMs, it just becomes a 
GetTrapAddress Call. 


Note: Testing to see if WaitNextEvent is implemented is not the same 
as testing to see whether MultiFinder is running.. Future systems may include 
WaitNextEvent whether or not MultiFinder is running. 


How can | tell if the MultiFinder Temporary Memory Allocation calls 
are implemented? 


The technique that’s used to determine this is similar to the above 
technique. In Pascal: 
FUNCTION TempMemCallsAvail: BOOLEAN; 


TYPE 
LongPtr = “Longint; 
CONST 
SwitchPtr = $282; (low-memory long-word global for switcher} 
Juggidispatch © S8F; (trap number of MultiFinder dispatch trap -- ToolTrap} 
UnImpiTrap = $9F; (trap number of unimplemented trap -- ToolTrap) 
VAR 
switcnP : LongPtr; 
BEGIN (TempMemCallsAvail) 
switch? := LongPtr (SwitchPtr); 
TempMemCallsAvail:= ((switchP” = 0) | (switenP* = - 1)) & 
(NGetTrapAddress(JugglDispatch, ToolTrap) <> 
NGet TrapAddress (UnImpiTrap, ioolTrap)); 
END; {TempMemCal lsAvail} 


ta 
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Introduction 


This document provides answers to some of the questions most 
frequently asked about MultiFinder. 


How can | tell if WaitNextEvent is implemented? 


Most applications should not need to tell if MultiFinder is running. Most 
of the time, the application really needs to know something like: “How can | tell if 
WaitNextEvent is implemented?” Here's a Pascal fragment that 


demonstrates how to check to see if WaitNextEvent is implemented: 
CONST 


WNETrapNum = $60; (trap number of WaitNextEvent) 
UnimpiTrapNum = $9F; (trap number of “*unimplemented trap”) 
VAR 


WNE IsImplemented : BOOLEAN; (is WaitNextEvent implemented} 


BEGIN 
(Is WaitNextEvent implemented? } 
WNEIsImplemented := NGetTrapAddress (WNETrapNum, ToolTrap) <> 
NGet TrapAddress (UnImplTrapNum, ToolTrap); 
{Main Event Loop} 
IF WNEIsImplemented THEN 


WaitNextEvent (..) 
ELSE BEGIN 


SystemTask; (for drivers, since we're calling GNE not WNE) 
GetNextEvent (~); 
END; (ELSE) 


END; 


In C: 


define SwitchPtr {long *} (0x282) 
tdefine JugglDispatch 0x8€ 
tdefine OnimplTrap 0x9€ 


Boolean TempMemCallsAvail () 


{ /“TempMemCallsAvail*/ 
return({({*SwitchPtr==#0) || (*SwitchPtr == -1)) &é 
(NGet TrapAddress(JuggliDispatch,ToolTrap) ‘= 
NGetTrapaddress (UnimplTrap, ToolTrap})}; 

} /*TempMemCallsAvail*/ 


This routine checks to see if the long word in $282 is -1 (Switcher has not 
run) or O (Switcher has run and quit). If one of these is true, it then compares 
the MultiFinder dispatch trap with the unimplemented trap. If the MultiFinder 
dispatch trap is implemented, then the MultiFinder Temporary Memory Calls 
exist. If the long word in $282 is not equal to either -1 or O, then Switcher is 
active, so MutiFinder isn't. 


How can | tell if my application is running in the background? 


To run in the background under MultiFinder, an application must have set 
the canBackground bit (bit 12 of the first word) in the SIZE resource. in 
addition, the accept SuspendResumeEvents bit (bit 14) should be set. 


An application can tell if it is running in the background if it has received 
a SUSPEND event but not a RESUME event ( the sample program Events 
demonstrates this). 


When exactly does juggling take place? 


Juggling takes place at WaitNextEvent/ GetNextEvent/EventAvail 
time. If you have the acceptSuspendResumeEvents bit set in the SIZE 
resource, you will receive SUSPEND/RESUME events. When you get a 
SUSPEND event (or, when you call EventAvail and a SUSPEND event has 
been posted), you will be juggled out the next time that you call 
WNE/GNE/EventAvail. When you receive a SUSPEND event, you are going 
to be juggled, so don't do anything to try to retain control (such as calling 
ModalDialog). 


Speaking of ModalDialog, MultiFinder will not SUSPEND your 
application when the frontmost window is a modal dialog, though background 
tasks will continue to get time. 


Can | “disable” SUSPEND/RESUME events by passing the 
appropriate event mask to WNE/GNE/EventAvail? 


SUSPEND/RESUME events are not queued, so be careful when 
masking out app4Evts. You will still get the event, all that will happen if you 
mask out app4Evts is that your application won't know when it is going to be 
juggied out (your application will still be juggled out when you call 
WNE/GNE/EventAvail). If your application sets a boolean to tell whether or not 
it's in the foreground or the background, you definitely don't want to mask out 
app4Evts. 
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Should my application use WaitNextEvent? 


Yes, this will enable background tasks to get as much time as possible. 
All user events that your program needs to handie will be passed to your 
application as quickly as possible. Applications that run in the background 
should try to be as friendly as possible. It's best to do things a small chunk at a 
time so as to give maximum time to the foreground application. “Cooperative 
multi-tasking” requires cooperation! 


You can use the sample programs provided in this seed package (Timer 
and Events) to determine how much time you should yield in your WNE call to 
ensure that other applications are getting sufficient background/foreground 
time. 


if your application calls waitNext Event, it shouldn't call SystemTask. 


Is there anything else that | can do to be particularly MultiFinder 
friendly? 


it is very important that you save the positions of windows that you open, 
so that the next time the user launches your application, the windows will go 
where she/he had them last. This greatly enhances the useability of 
MultiFinder. With data files, the window positions can be stored in either the 
resource or the data fork. 


If you have windows that aren't data windows (i.e. separate files), you 
can store information about their positions in one of two ways: in a separate 
configuration file or in a resource in your application. Using a separate 
configuration file is necessary if your application is shareable on AppleShare, 
since resource forks are not. The configuration file should be put in the folder 
that contains the currently open system folder (this is guaranteed to be a local, 
non-shared volume as opposed to a server volume). The vRefNum/WDRefNum 
of this folder can be obtained by calling SysEnvirons 
(SysEnvRec.sysVRefNum). The sample program Events (on disk 2 of this 
seed package) uses this technique. | 


Can | use a debugger with MuitiFinder? 


Yes, MacsBug will load normally, since it is loaded well before 
MultiFinder. Since TMON is currently installed as a startup application, you 
should Set Startup to it, then launch MultiFinder manually (by holding down 
Option-Command while double-clicking the MultiFinder icon) or use a program 
that will run multipie startup applications (such as Sequencer), making sure that 
TMON is run before MultiFinder. If you try to run TMON after MultiFinder has 
been installed, a system crash will result. 


it is necessary to check CurApName ($910) when you first enter a 
debugger (TMON users can anchor a window to $910) to see which layer 
(whose code, which low-memory globals and so on) is currently executing, 
especially if you entered the debugger by pressing the interrupt button. 
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What happened to animated icons under MultiFinder? 


Finder 6.0 no longer uses the mask that you supply in an ICN# to “punch 
a hole” in the desktop. Instead, it uses a default mask that consists of a solid 
black copy of the icon with no holes. 


How can | ensure maximal compatibility with MultiFinder? 


if you follow the guidelines presented in “Are You MultiFinder Friendly” 
you will stand a very good chance of being fully compatible with MultiFinder. If 
you find that you can't explicitly follow those guidelines, please contact 
Macintosh Developer Technical Support (AppleLink address: MACOTS MCI 
Mail address: 215-0798) for assistance. 
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Technical Note #126 discusses the new sublaunching feature of System 
4.1. If you are running MultiFinder and you use the technique demonstrated in 
that technical note, your application will be able to launch the desired 
application, but then MultiFinder will close your application (this is the way that 
_Launch works on non-MultiFinder systems). 


In order to keep your application open, set both high bits of 
LaunchF lags, that is: 


LaunchFlags:= $C0000000; {see p. 3 of the technote} 


The application that you launch will become the foreground application. 
Unlike non-MultiFinder systems, when the user quits the application that you 
have sublaunched, contro! will not necessarily return to your application, but 
rather to the next frontmost layer. 


Unlike non-MultiFinder systems, your application will continue to execute 
(if both high-bits of LaunchFlags are set), so be prepared! Calling Launch 
can now be thought of as a request to launch an application. The actual 
launch (and hence SUSPEND of your application) won't happen in the 
“Launch trap, but at a later time. 


“Launch now returns an error in register DO. You can check for DO < 0 
after the Launch to see if the Launch failed. ifDO >= O then the application 
will be launched. in Pascal, you could modify the code in TechNote #126 to 
retum an error as follows: 

FUNCTION LaunchIt (pLnch: pLaunchStruct) :OSErr; 

INLINE $205F, (MOVE.L (SP)+,A0 ;pointer to parameters in AQ} 
SA9F2, ( Launch) ... 
S3E80; {MOVE.W DO, (A7) ;get function result from DO) 


The wamings in the technote about using sublaunching still apply, but, if 


you still wish to use Sublaunching, we strongly recommend that you set both 
high bits of LaunchF lags. 
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YOU SHOULD CAREFULLY READ THE FOLLOWING 
TERMS AND CONDITIONS BEFORE USING THIS 
SOFTWARE. ANY DOWNLOADING, REPRODUCTION, 
COPYING OR OTHER USE OF THE SOFTWARE WILL 
CONSTITUTE ACCEPTANCE OF THESE TERMS AND 
CONDITIONS. 


SINGLE-COMPUTER END USER 
= SOFTWARE LICENSE AGREEMENT 


APPLE COMPUTER, INC. (‘Apple’) provides this software 
and licenses its use. You assume responsibility for the selection 
of the software to achieve your intended results, and for the 
installation and use of, and results obtained from, the software. 


LICENSE 
Pursuant to this license you may: 

1. Use the software only on a single Appie computer. You 
must obtain a supplementary license from Apple before 
using the software in connection with systems and multiple 
central processing units, computer networks or emulations 
on mainframe or minicomputers. 

2. Download the software only on media that is compatible 
with Apple manufactured cornputers. 

3. Copy the software into any machine readable form for 
backup purposes in support of your use of the software on 
the single Apple computer. 

4. Transfer the software and license to another party with a 
copy of this Agreement provided the other party reads and 

to accept the terms and conditions of this Agreement. 
you transfer the software, you must at the same time 
either transfer all copies, whether in printed or machine- 
readable form, to the same or destroy any copies not 
transferred. Apple grants a license to such other party under 
this Agreement and the other party will accept such license 
z its initial use of the software. If you transfer possession 
any copy of the software, in whole or in part, to another 
party, your license is automatically terminated, 
Tais software is protected by United States copyright law. 
»u must reproduce the Apple copyright notice on any copy of 
“me software. 

THIS SOFTWARE MAY BE ELECTRONICALLY DIS- 
TRIBUTED ONLY BY AUTHORIZED ELECTRONIC 
DISTRIBUTORS. IT MAY BE DOWNLOADED ONLY FOR 
PERSONAL OR NON-COMMERCIAL USES ON APPLE 
COMPUTERS AND MAY NOT BE REDISTRIBUTED OR 
USED FOR COMMERCIAL PURPOSES WITHOUT AN 
EXPRESS SOFTWARE DISTRIBUTION LICENSE FROM 
APPLE. These licenses are available from Apple's Software 


Licensing Pig 

YOU MAY NOT MODIFY, REVERSE COMPILE, DISAS- 
SEMBLE, NETWORK. RENT, LEASE, LOAN OR DIS- 
TRIBUTE THE SOFTWARE, OR ANY COPY, IN WHOLE 
OR IN PART. YOU UNDERSTAND THAT UNAUTHOR- 
IZED REPRODUCTION OF COPIES OF THE SOFTWARE 
OR UNAUTHORIZED TRANSFER OF ANY COPY OF THE 
SOFTWARE MAY SUBJECT YOU TO A LAWSUIT FOR 
DAMAGES, INJUNCTIVE RELIEF, AND ATTORNEY'S 


FEES. 
Apple reserves all rights not expressly granted to you. 


Export law assurances 


You agree and certify that neither the software and documen- 
tation nor any direct product thereof (1) is intended to be used 
for nuclear proliferation or any other purpose prohibited by the 
United States Export Administration Act of 1979, as amended 
(the “Act”) and the regulations promulgated thereunder, and 
(2) is being or will be downloaded, shipped, transferred or 
reexported, directly or indirectly, mto any country prohibited 
by the Act and the regulations promulgated thereunder. 


overnment End Users 
~ If you are acquiring the software on behalf of any unit or 
agency of the United States government. vou agree that: (a) the 
software is “Corrmercial Computer Software” as that term is 


defined in Paragraph 27.401 of the DoD S 


lement to the 
Federal Acquisition Regulations (the “Supplement”) or is 
within the equivalent classification of any other federal agen- 
cies' regulauions; (b) the software was developed at private 
expense, and no part of it was developed with goverment 
funds: (c) the government's use of the software is subject to 
"Restricted Rights” as that term is defined in clause 
$2.227-7013 (b)(3)(ii) of the Supplement or in the equivalent 
clause of any other f agencies’ regulations; (d) the 
software is a “trade secret” of Apple for all purposes of the 
Freedom of Information Act; and (e) each copy of the 
software will contain the following Restricted Rights Legend: 
“Restricted Rights Legend” 

Use, duplication or disclosure is subject to restrictions as 

set forth in subdivision (b\(3)(ii) of the Rights in 

Technical Data and Computer Software clause at FAR 

42.227-7013. Manufacturer: Apple Computer, Inc. 

20525 Mariani Avenue, Cupertino, Calfornia 95014. 

You agree to indemnify Apple for any liability, loss, costs 
and expense (including court cosis and reasonable attorneys 
fees) arising out of any breach of the provisions of this 
Agreement relating to use by the government. 


Term 


The license is effective until terminated. You may terminate it 
at any time by destroying the software together with all copies. 
The license will also terminate upon conditions set forth eise- 
where in this Agreement or if you fail to comply with any of 
the terms or conditions of this Agreement. You agree upon 
such termination to destroy all copies of the software. 


Disclaimer of Warranty 


The software is provided “as is” without warranty of any 
kind, either express or implied, with respect to its merchant- 
ability or its fimess for any particular purpose. The entire risk 
as to the quality and performance of the software is with you. 
Should the software prove defective, you (and not Apple or an 
Apple authorized representative) assume the entire cost of ail 

servicing, repair or correction. 

Apple does not warrant that the functions contained in the 
software will meet your requirements or that the operation of 
the software will be uninterrupted or error free or that defects in 
the software will be corrected. 

Some states do not allow the exclusion of implied warranties, 
so the above exclusion may not apply to you. This warranty 
gives you specific legal rights and you may also have other 
nghts which vary from state to stale. 


Limitation of Remedies 


In no event will Apple be liable to you for any lost profits, 
lost savings or other incidental, ial or consequential 
damages arising out of the use of or inability to use any soft- 
ware even if Apple or an authorized Apple representative has 
been advised of the possibility of such damages, or for any 
claim by any other party. 

Some states do not allow the limitation or exclusion of 
liability for incidental or consequential damages so the above 
limitation or exclusion may no apply to you. 

Apple's liability to you for actual damages for any cause 
whatsoever, and regardless of the form of the action, will be 
limited to the greater of $500 or the money paid for the soft- 
ware that caused the damages or that is the subject matter of, or 
is directly related to, the cause of action. 


General 


This Agreement, if any attempt to network, rent, lease, or 
sublicense the software, or, except as expressly provided in 
this Agreement, to transfer any of the rights, duties or obiiga- 
tions under this Agreement, becomes void. 

The Agreement will be construed under the laws of the state 
of California, except for that body of laws dealing with conflict 
of laws. If any provision of this Agreement shall be held by a 
court of competent jurisdiction to be contrary to law, that pro- 
vision will be enforced to the maximum extent permissible, 
and the remaining provisions of this Agreement shall remaia in 
full force and effect. 


ro 


ELOA 


APPLE 
PROGAAMIMES'S 


aD SS. EL SPla S 
ASSOCIATION 


AAA = 4, qm A, 
coo See iUa. Siras 


Sentia NA 24525 


PICT File 
Format Notes 


APDA# KMBPEN 


PICT File Format Notes 


Enclosed is documentation relating to the new version of PICT, the Macintosh graphic 
data file structure. If your application generates or receives image data, you will be 
particularly interested in this document. It describes the Macintosh PICT file format, the 
key differences between version 1 PICT and version 2 PICT, picture spooling, new 
pixMap structure for image data, and many compatibility issues that you will want to 
incorporate into your product. Also enclosed with this package are the Macintosh 
Technical Notes #21, 27, 120 and 154. These notes describe Version 1 PICT data 
structures and file formats, drawing to an offscreen buffer and error checking for the 
picture spooling code included in the PICT document. 


With the new PICT file format, Apple provides all application developers with a 
consistent way of capturing, modifying and replaying arditranly large scanned images 
as well as text and line data. In order to be compatible with future Apple products as 
well as other Macintosh applications, we strongly urge you to incorporate support for 
PICT into your application by using the QuickDraw picture structure described in this 
document. 


Note: with the exception of this cover page, this package is identical to a package of 
information sent to all Apple Certified Developers in July, 1987. 


Macintosh File Format 
& Picture Structure 
for 
Graphic Applications 


July 15, 1987 


Apple Technical Publications 


Copyright © 1987 Apple Computer, Inc. All rights reserved 


Contents 


Tide 


About These Notes 
Supplemental Reference Documents 
Terminology 
A Standard Format The Advantage to You As a Developer 
Use of QuickDraw Picture Format for Image Data 
Key Differences Berween Version 1 & 2 Pictures 
Picture Parsing 
How QuickDraw Defines a Picture 
Picture Spooling 
Spooling a Picture from Disk 
Spooling a Picture to a File 
Drawing to an Ofiscreen Pixel Map to Get Interactive Performance 
A New Set of grafProcs Routines 
10 An Eye Toward Compaability 
10 Picture Format 


E 


OD DCI NTNU Rh WN 


12 picComments 

12 Sample PICT File 

13 PICT Opcodes 

19 The New Opcodes - Expanded Format 


Figures & Tables 
Page Tide 


4 Figure 1. PICT File Format 

14 Table 1. Data Types 

15 Table 2. PICT Opcodes 

19 Table 3. Data Format of Version 2 PICT Opcodes 

21 Table 4. Data Types Found within New PICT Opcodes Listed in Table 3 


About these notes 


“This document, in addition to Inside Macintosh and Macintosh Technical Notes #21 , 27 and 120, 

“provides the information developers need to know in order to create or modify graphics application 
programs for the Macintosh. It describes the graphic data file structure, how it is parsed, the format 
used to define pictures in QuickDraw and Color QuickDraw, and the differences berween the new 
opcodes and those currently in use. It is written with particular consideration for the needs of 
scanner application developers and manufacturers, but applies in general to all developers of 
applications that generate or receive image data and do not directly deal with structured graphics. 


Apple’s main objective in releasing this information is to create a development environment that 
will ensure compatibility with existing products and spawn new graphics-oriented tools. These 
preliminary notes do not constitute a manual and should not be considered complete in their present 
form. While every attempt has been made to verify the accuracy of the information presented, it is 
subject to change without nouce. 
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Supplemental reference documents 
The Apple publications listed below are suggested reading to help understand QuickDraw pictures: 
© Inside Macintosh, Volumes I & IV contain detailed information about QuickDraw 


- Inside Macintosh, Volume V (currently in preliminary release); contains detailed 
information about Color QuickDraw 


« Macintosh Technical Notes #21 describes the internal format of the version 1 QuickDraw 
picture data structure 


e Macintosh Technical Notes #27 describes the PICT file format 
* Macintosh Technical Notes #120 describes drawing to an offscreen buffer 


* Macintosh Technical Notes #154 describes how to display large PICT files 


Terminology 
The following terms are used throughout this document. 
QuickDraw picture: A variable-sized QuickDraw data structure, consisting of picture 


opcodes and data, that is used to store graphics primitives for later 
playback. A version 2 picture can contain color information. 


PICT file type: A data-fork file that contains a 512 byte header, followed by a 
QuickDraw picture. 

PICT resource type: This is a resource which contains a QuickDraw picture (version 1 or 2). 

opcode: A pre-defined number within the QuickDraw picture that the 


QuickDraw function DrawPicture uses to determine what object to 
draw or what mode to change for subsequent drawing. 


graphic primitive: A data structure that specifies the geometry of basic graphical 
shapes, such as lines, arcs, ellipses, and rectangles. 


m 
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A standard format: the advantage to you as a developer. 


One of the outstanding features of the Macintosh computer has been the ease with which the user 
accesses graphic data created by different applications. Apple supports the PICT dara file as the 
vehicle for importing and managing scanned bitMaps and pixMaps into Apple/third party 
applications. Developers interested in creating or modifying their applications to be compatible 
with Apples’s graphic products should specify bit map or pixel map data using the QuickDraw 
picture structure described in this document. The graphic information can then be saved as a PICT 
data file. Because Apple supports this file format and picture structure, any application that 
recognizes the PICT file format should be able to read, display, and modify graphic data created by 
other Macintosh applications. 


The PICT file (defined in Macintosh Technical Note #27) is a data fork file with a 512-byte 
header, followed by a picture (see Figure 1). This data fork file contains a QuickDraw (and now, 
Color QuickDraw) data structure widun which a graphic application (using standard QuickDraw 
calls) places drawing primitives to represent an object or image graphic data. In the QuickDraw 
picture format, pictures consist of opcodes followed by picture data. 











PICT file 
(type=PICT) 


512-byte 
eader 


= 
oO 


picFrame 







This fork is 
empty in 
PICT files 





picture data 


EndOfPicture 


«Figure 1. PICT file format. . 


With the introduction of Macintosh II, the QuickDraw picture structure has been extended to 
include new color graphics opcodes, as well as enable future expandibility. The new opcodes 
solve many of the major problems encountered by developers in using PICT files. For example, it 
is now possible to specify the resolution of bitmap data. Color can also be specified, but only 
chunky pixels (contiguously stored pixel components) are currently recognized by Color 
QuickDraw. Your application only needs to generate or recognize the chunky pixel format This 
format is indicated by an image or pixMap with a cmpCount =1, 


Most existing applications work fine, without modification, with version 2 pictures. On a 
Macintosh H, version 2 pictures will draw in color (if drawn direcily to the screen). Currendy, 
they will print using the old QuickDraw colors. Eventually, new print drivers will be able to take 
advantage of the new color information. 
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On a Macintosh 512 enhanced, Macintosh Plus, and Macintosh SE, a patch in the System file 
beginning with version 4.1 provides QuickDraw with the capability to convert and display version 
2 pictures. The original Macintosh and Macintosh 512 cannot display version 2 pictures. 


Applications that generate pictures in the QuickDraw picture format are free to use any or all 
available features to support their particular needs. Some will use only the pixMap primiave. You 
may wish to include comments in the picture that are pertinent to the needs of your application. In 
general, put a minimal amount of information in your PICT files and avoid redundancy. It is 
reasonable for receiving applications to ignore picture opcodes that are not needed. 


For those developers interested in generating picture data on non-Apple CPUs, the QuickDraw 
internal opcodes are included at the back of this document. For example, the universiry community 
may wish to generate ray-waced images on mainframes and display them in the Macintosh 
environment through use of the PICT file format and QuickDraw picture structure. 


Use of QuickDraw Picture Format for Image Data 


For developers, there are advantages to using the QuickDraw picture format to display images in 
their graphics applications: 


« Because the PICT structure is supported by Apple at the system level, it will always be 
considered in upgrade paths to new architectures. 


- Establishing a standard format for image data has enormous advantages for software 
developers interested in graphic data interchange between applications. If, for example, all 
scanner peripherals support PICT as the graphic data file format, the task of importing data 
would then be reduced to parsing a single file format. 


Key differences between version 1 & 2 pictures 


The major differences between version 1 and 2 pictures are listed below. 


- version 1 opcodes are a single byte; version 2 opcodes are 2 bytes in length. This means 
that old opcodes in a version 2 picture take up two bytes, not one. 


' e version 1 data may start on byte boundaries; version 2 data is always word-aligned. 


- in version 2, the high bit of the rowBytes field is used to indicate pixMap instead of 
bicMap; pixData then replaces bitData. 


* e all unused version 2 opcodes, as well as the number of data bytes associated with each, 
have been defined. This was done so that picture parsing code can safely ignore unknown 
opcodes, enabling future use of these opcodes in a backward-compatible manner. . 


Picture parsing 


The first 512 bytes of a PICT data file contain application-specific header information. Each 
QuickDraw (and Color QuickDraw) picture definition consists of a fixed-size header containing 
information about the size, scaling, and version of the picture, followed by the opcodes and picture 
data defining the objects drawn between the OpenPicture and ClosePicture calls. 
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When the OpenPicture routine is called and the port is an old grafPort, a version | picture is 
opened. When the OpenPicaure routine is called and the port is a CGrafPort, then a version 2 
picture is opened. If any fields in the grafPorr are different than the default entries, those fields thas 
are different get recorded in the picture. 


Version 4.1 of the Macintosh System file incorporates a patch to QuickDraw that will enable 
QuickDraw (on machines with 128K or larger ROMs) to parse a version 2 PICT file, read it 
completely, attempt to convert all Color QuickDraw color opcodes to a suitable black-and-white 
representation, and draw the picture in an old grafPort. If you are trying to display a version 2 
picture on a Macintosh without the system patch, QuickDraw won't be able to read (or display) the 
picture data but it shouldn't crash your machine. 


On the Macintosh II, old pictures can also be played back in new grafPorts. You should only use 
old drawing commands in old pictures. In new pictures, old and new drawing commands can be 
intermixed. 
How QuickDraw defines a picture 
The Pascal record structure of version 1 and 2 pictures is exactly the same. In both, the picture 
begins with a picSize, then a picFrame (rect), followed by the picture definidon data. Since a 
picture may include any sequence of drawing commands, its data structure is a variable-length 
entity. It consists of two fixed-length fields followed by a variable-length field: 

i W i w pi 


TYPE Picture = RECORD 


picSize: INTEGER; {low order 16 bits of picture size; 
this is not useful information} 
pict rame: Rect; {picture frame, used as reference for 


scaling when the picture is drawn} 
(picture definition data} 
END; 


To maintain compatibility with the original picture format, the picSize field has not been changed in 
version 2 pictures. However, the information in this field is only useful if your application 
supports version 1 pictures not exceeding 32K bytes in size. Because pictures can be mucn larger 
than the 32K limit imposed by the 2-byte picSize field, use the GetHandleSize call to determine 
picture size if the picture is in memory or the file size returned in pBFGetInfo if the picture resides 
in a file. 


The picFrame field is the picture frame that surrounds the picture and gives a frame of reference for 
Scaling when the picture is played back. The rest of the structure contains a compact representation 
of the image defined by the opcodes. The picture definition data consists of a sequence of the 
opcodes listed in Table 2, each followed by zero or more bytes of data. Every opcode has an 
implicit or explicit size associated with it that indicates the number of data bytes following that 
opcode, ranging from 2 to 2 32 bytes (this maximum number of bytes applies to version 2 pictures 
only. 
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Picture spooling 


In the past, images rarely exceeded the 32K practical limit placed on resources. Today, with the 
advent of scanners and other image input products, images may easily exceed this size. This 
increase in image size necessitates a means for handling pictures that are too large to reside enarely 
in memory. One solution is to place the picture in the data fork of a PICT file, and spool it in as 
needed. To read the file, an application need simply replace the QuickDraw default getPicProc 
routine with a procedure (getP{CTData) that reads the picture data from a disk file; the disk access 
would be transparent. Note that this technique applies equally to version 1 (byte-opcode) and 
version 2 (word-opcode) pictures. 


Spooling a picture from disk 


In order to display pictures of arbitrary size, an application must be able to import a QuickDraw 
picture from a file of type PICT. (This is the file type produced by a Save as... fom MacDraw 
with the PICT option selected.) What follows is a small program fragment that demonstrates how 
to spool in a picture from the data fork of a PICT file. The picture can be larger than the historical 
32K resource size limitation. 


Note: To better understand how to provide additional error 
checking during picture spooling, refer to Macintosh Technical 
Notes #154, “Displaying Large PICT Files”. 


{ the following variable and procedure must be at the main level of the program | 
VAR 
globalRef: INTEGER: 


PROCEDURE GerPICTData (dataPt=: Ptr; byteCount: INTEGER); { replacement for 
getPicProc routine | 


VAR 
err : INTEGER; 
longCouns: LONGINT; 


BEGIN 

longCount := byteCount; { longCount is a Pascal VAR parameter and 
must be a LONGINT } 

erz := FSRead(globalRef, longCount, dataPt =); 

{ ignore errors here since it is unclear how to handle them } 

END; s 
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PROCEDURE GacandDrawpICTSile: ( procedure to draw in a picture “om à PITT five 
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VAR 


BEGIN 


selected by the user } 


wher: Point: { where to display dialog } 

reply: SFReply: í reply record } 

myFileTypes: setypeList; { more of the Standard File goodies } 
NumFileTypes: INTEGER; 

err: OSEFI: | 
myProcs: QDP rocs; ( use CQDProcs for a CGrafPort (a color window) | 
prct#and: PicHandle: [ we need a picture handle for cawpicrure | 
LongCount : LONGINT; 


my?S: varamslockRec;» 
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NumFileTypes :* 1; { Display PICT files } 
myFileTypes[0) := 'PICT'; 
SrGarrile(wher,'',NIL, NumfileTypes,myFileTypes, NIL, reply): 
IF reply.good THEN BEGIN 
erz := FSOpen(reply. fname, reply.vrefnum, globalRe£f); 


SetstdProcs (myProcs); { use SetStdCPracs for a CGrafPort | 
myWindow* .grafProcs := @myProcs; 
my?rocs.get?icProc := AGecPICTDAta; 


pICTHand := PicSandle (NewHandle(SizeOf (Picture))); { get one 
the size of (size word + frame rectangle) | 


{ skip (so to speak) the MacOraw header block ) 

err :m Setrros (globalRef, fsFromStart, 512); 

longCount := Size0f (Picture); 

{ read in the (obsolete) size word and the picture frare } 
err := FSRead (globalRef, longCount, Ptr (PICTHand”)); 


DrawPicture (PICTHand, PICTHand**.picframe) ; 

{ inside of DrawPicture, QD makes repeated calls to gerPicProc 
to get actual picture opcodes and data. Since we have 
intercepted GetPicProc, QD will call myProcs to get 
getPicProc, instead of calling the default procedure } 


err := FSClose(globalRef); 


myWindow”.grafProcs := NIL; 
DisposHandle (Handle (PICTHand) }; 


END; ( IF reply.good | 
END; 


Spooling a picture to a file 


Spooling a picture out to a file is equally straightforward. By replacing the standard putPicProc 
with your own procedure, you can create à PICT file and spool the picture data out to the file. 


ty 
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Drawing to an offscreen pixel map to get interactive 
performance 


With the advent of high resolution output devices such as laser printers, the need has arisen to 
support bit-map images at resolutions higher than those supported by the screen. In order to speed 
up the interactive manipulation of high-resolution pixel-map images, developers may want to first 
draw them into an off-screen pixel map at screen resolution and retain this screen version as long 
as the document is open. 


Note: You can use the formula shown under the section on 
"Sample PICT file” to calculate the resolunon of the source data. 
How to draw into an offscreen pixMap is described in Macintosh 
Technical Note #120. 


A new set of grafProcs routines 


The entire opcode space has been defined or reserved, as shown in Table 2, and a new set of 
routines has been added to the grafProcs record. The purpose of these changes is to provide 
support for anticipated future enhancements in a way that will not cause old applications to crash. 
How this works is that when Color QuickDraw encounters an unused opcode, it calls the new 
opcodeProc routine to parse the opcode data. By default, this routine simply ignores the data, 
since no new opcodes are defined (other than HeaderOp, which is also ignored). 


Color QuickDraw has replaced the QDProcs record with a CQDProcs record. In a new grafPort, 
you should never use the SetStdProcs routine. If you do, it will return the old QDProcs record, 
“which will not contain an entry for the stdOpcodeProc. If you do not use the new SetStdCProcs 
routine to parse the unused opcodes, the first color picture that you try to display may crash your 
system. 


Extensions to the QDPROCS record 


opcodeProc EQU $34 (pointer) 
newProcl EQU $38 [pointer] 
newProc2 EQU S5€ [pointer] 
newProc3 EQU $40 (pointer) 
newProc4 EQU S44 [pointer] 
newProc5 EQU S48 [pointer] 
newProcó EQU S4C [pointer] 
CQDProcsRec EQU $50 size of QDProcs record 


% 
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An Eye Toward Compatibility 


Many applications already support PICT resources larger than 32K. The 128K ROMs (and later) 
allow pictures as large as memory (or spooling) will accommodate. This was made possible by 
having QuickDraw ignore the size word and simply read the picture until the end-of-picture opcode 
is reached. 


For maximum safety and convenience, let QuickDraw generate and interpret your 
pictures. 


While Apple has provided you with the data formats that allow you to read or write picture data 
directly, we recommend that you always let DrawPicture or OpenPicrure and ClosePicture process 
the opcodes. 


One reason to read a picture directly by scanning the opcodes would be to disassemble it to, for 
example, extract a Color QuickDraw pixel map to save off in a private data structure. This 
shouldn't normally be necessary, unless you are working with an application running on a CPU 
other than the Macintosh. You wouldn't need to do it, of course, if you were using Color 
QuickDraw. 


If you do look at the picture data, be sure and check the version information. You may want to 
include an alert (dialog box) in your application that indicates to the user when a picture was 
created using a later version of the picture format than currently recognized by your application, 
letting them know that some elements of the picture cannot be displayed. Lf the version informanon 
indicates a QuickDraw picture version later than the one recognized by your application, your 
program should skip over the new opcodes and only attempt to parse the opcodes it knows. 


As with reading picture data directly, it is best to use QuickDraw to create data in the PICT format 
If you do have a need to create PICT format data directly, it is essential that you understand and 
follow the format presented in Table 2 and thoroughly test the data produced on both color and 
black and white Macintosh machines. 


Apple does not guarantee that a picture which wasn’t produced by QuickDraw will 
work. 


Picture Format 


This section describes the internal structure of the QuickDraw picture, consisting of a fixed-length 


header (which is different for version 1 and version 2 pictures), followed by variable-sized picture 
data. Your picture structure must follow the order shown in the examples below. 


The two fixed-length fields, picSize and picFrame, are the same for version 1 and version 2 
pictures. | 


picSize: INTEGER; {low-order 16 bits of picture size} 
picframe: RECT; (picture frame, used as scaling reference} 


Following these fields is a variable amount of opcode-driven data. Opcodes represent drawing 


commands and parameters that affect those drawing commands in the picture. The first opcode in 
any picture must be the version opcode, followed by the version number of the picture. 
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Pi Definition: Version} 
Picnure Header - fixed size of 2 bytes: 


$11 BYTE (version opcode) 
$01 BYTE (version number of picture) 


Picrure Definition Data - variable sized: 


opcode BYTE (one drawing command) 
data... 

opcode BYTE {one drawing command} 
data . 

SET (end-of-picture opcode} 


In a version 1 picture, the version opcode is $11, which is followed by version number SOL. 
When parsing à version 1 picture, Color QuickDraw (or a patched QuickDraw) assumes it is 
reading an old picture, fetching a byte at a time as opcodes. An end-of-picture byte (SFF) after the 
last opcode or data byte in the file signals the end of the data steam. 


nition: V 
Picnure Header - fixed size of 30 bytes: 


$0011 WORD {version opcode} 

$02FF WORD {version number of new picture} 
$0C00 WORD {reserved header opcode} 

24 bytes of data (reserved for future Apple use} 


Picture Definition Data - variable sized: 


opcode WORD (one drawing command) 
data... 

opcode WORD {one drawing command) 
data... 

SOOFF WORD (end-of-picture opcode} 


In a version 2 picture, the first opcode is a two-byte version opcode ($0011). This is followed by a 
two-byte version number (S02FF). On machines without the 4.1 System File, the first $00 byte is 
interpreted as a no-op and is skipped, then the $11 is interpreted as a version opcode. On a 
Macintosh II (or a Macintosh with System File 4.1 or later), this identifies the picture as a version 
2 picture, and all subsequent opcodes are read as words (which are word-aligned within the 
picture). On a Macintosh without the 4.1 System patch, the $02 is read as the version number, then 
the SFF is read and interpreted as the end-of-picture opcode. For this reason, DrawPicture 
terminates without drawing anything. 


For future expandibility, the second opcode in every version 2 picture must be a reserved header 
opcode, followed by 24 bytes of data that are not used by your application. 
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picComments 


If your application requires capability beyond thar provided by the picture opcodes, the 
picComment opcode allows data or commands to be passed directly to the output device. 
picComments enable MacDraw, for example, to reconstruct graphics primitives not found in 

= QuickDraw (e.g., rotated text) that are received either from the clipboard or from another 
application. picComments are also used as a means of communicating more effectively with the 
LaserWriter and with other applications via the scrap or the PICT data file. 


Because some operations (like splines and rotated text) can be implemented more efficiendy by the 
LaserWriter, some of the picture comments are designed to be issued along with QuickDraw 
commands that simulate the commented commands on the Macintosh screen. If the printer you are 
printing to has not implemented the comment commands, it ignores them and simulates the 
operations using the accompanying QuickDraw commands. Otherwise, it uses the comments to 
implement the desired effect and ignores the appropriate QuickDraw-simulated commands. 


Note: The picture comments used by MacDraw are listed and 
described in Macintosh Technical Note #27. 


If you are going to be producing or modifying your own picture, the structure and use of these 
comments must be precise. The comments and the embedded QuickDraw commands must come in 
the correct sequence in order to work properly. 


Note: Apple is currently investigating a method to register 
picComments. If you intend to use new picComments in your 
application, you must contact Apple's Developer Technical Support 
to avoid conflict with picComment numbers used by other 
developers. 


Sample PICT file 


An example of a version 2 picture data file which can display a single image is shown on the 

following page. Applications that generate picture data should set the resoludon of the image 

source data in the hRes and vRes fields of the PICT file. We recommend, however, that you 

calculate the image resolution anyway using the values for srcRect and dstRect according to the 
y following formulas: 


horizontal resolution (hRes) = width of srcRect x 72 
- width of dstRect 


height of srcRect x 72 


vertical resolution (vRes) = j 
height of dstRect 


“anae 
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PICT file example 


Size 


Name 


Description 


(in bytes) 


Zz 
8 


Picture Definition Data: 


On 


PNNNHNARARNNONN APH RNNN 


(ctSize+1) * 


9 00 CA CONN PD 


see Table 4 
2 


PICT Opcodes 


The opcode information in Table 
application-generated PICT files. 


picSize 
picFrame 


version op 
version 
Header op 
size 
fBBox 
reserved 


opbitsRect 
rowBytes 
bounds 
pm Version 
packT ype 
packsize 
hRes 

vRes 
pixelType 
pixelSize 


_ empCount 


cmpSize 
planeB ytes 
pmTable 
pmReserved 
ctseed 
transindex 
ctSize 
CTTable 
srcRect 
dstRect 
mode 
pixData 


endPICT op 


low word of picture size 
rectangular bounding box of picture, at 72 dpi 


version opcode = $0011 

version number = $02FF 

header opcode = $OCOO 

total size of picture in bytes (=-1 for v.2 pictures) 
fixed-point bounding box (=-1 for v.2 pictures) 
reserved for future Apple use (=-1 for v.2 pict.) 


BitMap opcode = $0090 

integer, must have high bit set to signal pixMap 
rectangle, bounding rectangle at source resolution 
integer, pixMap version number 

integer, defines packing format 

Longint, length of pixel data 

fixed, horizontal resolution (dpi) of source data 
fixed, vertical resolution (dpi) of source dara 
integer, defines pixel type 

integer, number of bits in pixel 

integer, number of components in pixel 
integer, number of bits per component 
Longint, offset to next plane 

color table = O 

reserved = 0 

Longlnt, color table seed 

integer, index of transparent pixels 

integer, number of entries in CT Table 

color lookup table data 

rectangle, source rectangle at source resolution 
rectangle, destination rectangle at 72 dpi resolution 
integer, transfer mode 

pixel data 


end-of-picture opcode = SOOFF 


2 (on pages 15-19) is provided for the purpose of debugging 
Your application should generate and read PICT files only by 


using standard QuickDraw or Color QuickDraw routines (OpenPicture, ClosePicture). 
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The data types listed below are used in the in Table 2 opcode definitions. Data formats are 
described in Inside Macintosh, Volume I. 


Table 1. Data types 


EE mm 


Type Size 


MRE CC) 


vl opcode 1 byte 

v2 opcode 2 bytes 

integer 2 bytes 

long integer 4 bytes 

mode 2 bytes 

point 4 bytes 

0..255 | byte 

—128..127 1 byte (signed) 

TECI 8 bytes (top, left, bottom, right: integer) 
poly 10+ bytes 

region 10+ bytes 

fixed-point number 4 bytes 

patem 8 bytes 

rowbytes 2 bytes (always an even quantity) 


Valid picture opcodes are listed in Table 2. New opcodes or those altered for version 2 picture 
files are indicated by a leading asterisk (*). Refer to Inside Macintosh, volume V for specific 
details on the new Color QuickDraw routines. The unused opcodes found throughout the table are 
reserved for Apple use. The length of the data that follows these opcodes is pre-defined, so if they 
are encountered in pictures, they can simply be skipped. By default, Color QuickDraw reads and 
then ignores these opcodes. 


Notes For Table 2: 


1. The opcode value has been extended to a word for version 2 pictures. Remember, opcode 
size = 1 byte for version 1. 


2. Because opcodes must be word aligned in version 2 pictures, a byte of 0 (zero) data is 
added after odd-size data. 


3. The size of reserved opcodes has been defined. They can occur only in version 2 pictures. 
> 4. Allunused opcodes are reserved for future Apple use and should not be used. 


5. For opcodes $0040 - $0044: rounded-corner rectangles use the setting of the ovSize point 
(refer to opcode $0008) 


6. For opcodes $0090 and $0091: data is unpacked. These opcodes can only be used for 
rowbytes less than 8. 


7. For opcodes $0100 - $7F FF: the amount of data for opcode $nnXX = 2 * nn bytes 
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Table 2. PICT opcodes 


Opcode Name 


$0000 
$0001 
$0002 
$0003 
$0004 
$0005 
$0006 
$0007 
$0008 
$0009 
SOO0A 
S000B 
$000C 
$000D 
SOO0E 
S000F 


$0010 
$0011 
$0012 
$0013 
$0014 
$0015 
$0016 
$0017 
$0018 
$0019 


$0023 
$002C 
$002D 
$002E 
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NOP 
Clip 
BkPar 
TxFont 
TxFace 
TxMode 
SpExra 
PnSize 
PnMode 
PnPat 
FillPat 
OvSize 
Origin 
TxS ize 
FgColor 
BkColor 


TxRato 

Version 

*BkPixPat 

*PnPixPat 

*FillPixPat 
*PnLocHFrac 
*ChExra 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*RGBFgCol 
*RGBBxCol 

*Pilite Mode 
*HiliteColor 

*DefHilite 

*OpColor 


Line - 
LineFrom f 
ShortLine 
ShortLineFrom 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
LongText 

DHText 

DVText 

DHDVText 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 


Description 


nop 

clip 

background pattern 

text font (word) 

text face (byte) 

text mode (word) 

space extra (fixed point) 
pen size (point) 

pen mode (word) 

pen partem 

fill partem 

oval size (point) 

dh, dv (word) 

tex: size (word) 
foreground color (long) 
background color (long) 


numer (point), denom (point) 
version (byte) 

color background pattern 
color pen pattern 

color fill pattern 

fractional pen position 

extra for each character 
opcode 

opcode 
opcode 

RGB foreColor 

RGB backColor 

hilite mode flag 

RGB hilite color 

Use default hilite color 

RGB OpColor for arithmetic modes 


poLoc (point), newPt (point) 

newPt (point) 

pnLoc (point, dh, dv (-128. . 127) 

dh, dv (-128. . 127) 

opcode + 2 bytes data length + data 

opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 

opcode + 2 bytes data length + data 
txLoc (point), count (0. .255), text 
dh (0. .255), count (0. .255), text 
dv (0. .255), count (0. .255), text 


Data Size 


gion size 


— OO PRN Ap CO) RAIO O 


variable: see Table 3 
variable: see Table 3 


variable: see Table 3 


SOON 


variable: ses Table 3 
variable: ses Table 3 


o see Table 3 
vanable: see Table 3 


to O fa oo 


2+ data length 
2+ data length 
2+ data length 
2+ data length 
5 + text 
2 + text 
2 + text 


dh, dv (0. .255), count (0. .255), text 3 + text 
opcode + 2 bytes data length + data 2+ data length 
opcode + 2 bytes data length + data 2+ data length 
opcode + 2 bytes data length + data 2+ data length 
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Table 2. PICT opcodes (continued) 


Opcode Name 


$002F 


$0030 
$0031 
$0032 
$0033 
$0034 
$0035 
$0036 
$0037 
$0038 
$0039 
$003.A 
$003B 
$003€C 
S003D 
S005E 
S003F 


$0040 
$0041 
$0042 
$0043 
$0044 
$0045 
$0045 
$0047 
$0043 
$0049 
SOOLA 
$004B 


*reserved for Apple use 


frameRect 

paintRect 

eraseRect 

invertRect 

fillRect 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
frameSameRect 
paintSameRect 
eraseSameRect 
invertSameRect 
fillSameRect 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 


frameRRect 

paintRRect 

eraseRRect 

invertRRect 

fillRRect i 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
frameSameRRect 
paintSameRRect 
eraseSameRRect 
invertSameRRect 
fillSameRRect 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 


frameOval 

paintOval 

erase Oval 

invertOval 

AllOval 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
frameSameOval 
paintSameOval 
eraseSameOval 
invertSameOval 
filiSameOval 
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Description 


opcode + 2 bytes data length + dara 


rect 
rect 
rect 
rect 


rect 
opcode + 8 bytes data 
opcode + 8 bytes dara 
opcode + 8 bytes dar 
rect 


rect 

rect 

rect 
rectangle 
opcode 
opcode 
opcode 


rect (see Note # 5 on page 13) 
rect (see Note # 5 on page 15) 
rect (see Nore # 5 on page 13) 
rect (see Note # 5 on page 13) 
rect (see Note # 5 on page 13) 
opcode + 8 bytes data 
opcode + 8 bytes dara 
opcode + 8 bytes dam 


rect 


rect 
opcode + 8 bytes data 
opcode + 8 bytes data 
opcode + 8 bytes data 
rect 
rect 
rect 
rect 
rect 


Data Size 


y 


2+ data length 


O O O O O 00 00 00 00 06 00 00 00 O O O O O O O O aa 0000 00 oa 00 09 oa O O O O O O O O oo oa oo 00 06 CO 60 Oa 
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Table 2. PICT opcodes (continued) 


Opcode Name Description Data Size 


a perene seen | | q 817), 44-7:) ERA 


SOOSD  ‘*reserved for Apple use opcode 0 

SOOSE *reserved for Apple use opcode 0 

SOOSF  *reserved for Apple use opcode 0 

$0060 frame Arc rect, startAngle, arcAngle 12 

$0061 paincArc rect, startAngle, arcAngle 12 

$0062 erase Arc rect, startAngle, arcAngle 12 

$0063 inventár rect, startAngle, arcAngle 12 

$0064 fllArc rect, startAngle, arcAngle 12 

$0065 *reserved for Apple use opcode + 12 bytes 12 

$0066 *reserved for Apple use opcode + 12 bytes 12 © 

$0067 *reserved for Apple use opcode + 12 bytes 12 

$0068 frameSameArc rect 4 

$0069 paintSame AT rect 4 

$S006B invertSame Arc rect 4 

S006C = fillSameArc rect 4 

$006D reserved for Apple use opcode + 4 bytes 4 

SOO6E ‘reserved for Apple use opcode + 4 bytes 4 

$006F  #$ *reserved for Apple use opcode + 4 bytes 4 

$0070  framePoly poly polygon size 
$0071 - paintPoly poly polygon size 
$0072 | erasePoly poly polygon size 
$0073 invertPoly poly polygon size 
$0074 fillPoly poly polygon size 
$0075 *reserved for Apple use opcode + poly 

$0076 *reserved for Apple use opcode + poly 

$0077 *reserved for Apple use opcode word + poly 

$0078 frameSamePoly (not yet implemented - same as 70, etc.) 0 

$0079  paintSamePoly (not yet implemented) 0 

$007A  eraseSamePoly (not yet implemented) 0 

$007B  invernSamePoly {not yet implemented) 0 

$007C 'fillSamePoly (not yet implemented) 0 

$007D ‘reserved for Apple use opcode 0 

$007E ‘*reserved for Apple use opcode 0 

$007F *reservedfor Apple use opcode 0 

$0080 frameRgn rgn region size 
$0081 paintR gn rgn region size 
$0082 eraseRgn ren region size 
$0083 invertRgn Tgn region size 
$0084 fillRen ren region size 
$0085 *reserved for Apple use opcode + rgn region size 
$0086 *reservedfor Apple use opcode +rgn region size 
$0087 *reserved for Apple use opcode + rgn region size 
$0088 frameSameRgn (not yet implemented - same as 80, etc.) 0 

$0089  paintSameRgn (not yet implemented) 0 

SOO8A  eraseSameRgn (not yet implemented) Q 
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Table 2. PICT opcodes (continued) 


Opcode Name 


S008B 
$008C 
$008D 
SOO8E 
S008F 


$0090 
$0091 
$0092 
$0093 
$0094 
$0095 
$0096 
$0097 
$0098 
$0099 
SO09 A 
$009B 
$009C 
$009D 
SO09E 
S009F 


SOOAO 
SOOA! 
SOOA2 
SOOAF 
$00B0 


$00CF 
$00D0 
SOOFE 
$OOFF 
$0100 


SOLEF 


nvertSameRgn 
fillSameR gn 

*reserved for Apple use 
*reserved for Appie use 
*reserved for Apple use 


*BitsRect 

*BitsRgn 

“reserved for Apple use 
*reserved for Apple use 
“reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*PackBitsRect 
*PackBitsRgen 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 


ShortComment 
LongComment 
*reserved for Apple use 


*reserved for Apple use 


*reserved for Apple use 


*reserved for Apple use 
“reserved for Apple use 
*reserved for Apple use 
opEndPic 


*reserved for Apple use 


*reserved for Apple use 
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Description 


(not yet implemented) 
(not yet implemented) 
opcode 
opcode 
opcode 


copybits, rect clipped 

copybits, rgn clipped 

opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 


opcode word + 2 bytes data length + data 
variable: see Table 3 
variable: see Table 3 


packed copybits, rect clipped 

packed copybits, rgn clipped 

opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 
opcode + 2 bytes data length + data 


kind (word) 

kind (word), size (word), data 
opcode + 2 bytes data length + dara 
opcode + 2 bytes data length + dara 


opcode 


opcode 

opcode + 4 bytes data length + data 
oper `- + 4 bytes data length + data 
end picture 


opcode + 2 bytes data 


opcode + 2 bytes data 


Data Size 


Vv 


0000 


variable: see Table 3 
variable: see Table 3 


2+ data length 
2+ data length 
2+ data leagth 
2+ data length 
2+ data length 
2+ data length 


2+ data length 
2+ data length 
2+ data length 
2+ data length 
2+ data length 
2+ data length 
2 

4+data 

2+ data length 
2+ data length 


0 


0 
4+ data length 
4+ data length 
2 
2 
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Table 2. PICT opcodes (continued) 


Opcode Name Description Data Size 
$0200 reserved for Apple use opcode + 4 bytes data l 4 

SOBFF *reserved for Apple use opcode + 4 bytes data 22 

SOCOO  HeaderOp opcode 24 

SOCO1:  *reserved for Apple use opcode + 4 bytes data 24 

$7F00 *reserved for Apple use opcode +254 bytes data 254 

S7FFF *reserved for Apple use opcode + 254 bytes data 254 

$8000 *reserved for Apple use opcode Q 

$80FF *reserved for Apple use opcode 0 

$8100 *reserved for Apple use opcode + 4 bytes data length + data 4+ dara length 


SFFFE “reserved for Apple use opcode + 4 bytes data length + data 4+ data length 


The new opcodes - expanded format 
The expanded format of the version 2 PICT opcodes are shown in Table 3 below. 
Table 3. Data format of version 2 PICT opcodes 


Opcode Name Description 
$0012 BkPixPat color background pattern 
$0013 PnPixPat color pen pattern 
$0014 FillPixPat color fill pattern 
if patType = ditherPat 
then 
PatT ype: word; ( pattern type = 2 } 
Pat] Dara: Pattern; { old pattern data } 
RGB: RGBColor, (desired RGB for pattern } 
E else : 
i PatType: word; ( panem type = 1 } 
Pat] Data: Pattern; ( old pattem data ) 
pixMap: { pixMap format shown below } 
colorTable: { color table format shown below } 
pixData: { pixData format shown below 
end; 
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Table 3. Data format of version 2 PICT opcodes (continued) 


Opcode Name Description 
$0015  PnLocHFrac fractional pen position 
pnLocHF me: word: ( see Inside Macintosh for format } 
If prLocurrac O 1/2, it is always put to the picture before each text drawing operation. 
$0016 ChExtra extra for each character 
chExma: word: { see Inside Macintosh for format } 


After chExtra changes, it is put to picture before next text drawing operation. 


$OO1A RGBFgCol -= RGB foreColor 

$001B RGBBkCol RGB backColor 

$001D HiliteColor RGB hilite color | 

$001F OpColor RGB OpColor for arithmetic modes 
RGB: RGBColor, { desired RGB for fg/bk } 


(see Inside Macintosh, Volume V for data structure) 
$001C HiliteMode hilite mode flag 
No data. This opcode is sent before a drawing operation that uses the hilite mode. 
SOOLE DefHilite Use default hilite color 
No data. Set hilite to default (from low memory). 


The next four opcodes ($0090, $0091, $0098, $0099) are modifications of existing (version 1) 
opcodes. The first word following the opcode is the rowBytes. If the high bit of the rowBytes is 
set, then it is a pixMap containing multiple bits per pixel; if it is not set, it is a bitMap containing 
one bit per pixel. In general, the difference between version 1 and 2 formats is that the pixMap 
replaces the bitMap, a color table has been added, and pixData replaces the bicData. 


Note: Opcodes $0090 and $0091 are only used for rowbytes less 


ê than 8. à 

$0090  BitsRect copybits, rect clipped 
pixMap: { described in Table 4 ) 
colorTable: ( described in Table 4 ) 
srcRect: Rec { source rectangle } 
dstRect: Rect, { destination rectangle } 
mode: Word; { transfer mode (may include new transfer modes) } 
PixData: { described in Table 4 } 
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Table 3. Data format of version 2 PICT opcodes (continued) 


a roer 


Opcode Name 


$0091 


$0098 


$0099 


BitsRgn 


dstRect: 


ixMap 


p : 
colorTable: 


srcRect: 


mode: 
maskRgn: 
PixData: 


PackBitsRect 


pixMap: 
colorTable: 
srcRect: 
dstRect: 
mode: 
PixData: 


PackBitsRgn 


pixMap: 
colorTable: 
stceRect: 
dstRect: 
mode: 
maskR gn: 
PixDan: 


Description 


copybits, rgn clipped 


Rect, 
Word; 


Ren; 


{ described in Table 4 } 

( described in Table 4 } 

{ source rectangle } 

{ destination rectangle } 

( transfer mode (may include new transfer modes) } 
{ region for masking } 

{ described in Table 4 } 


packed copybits, rect clipped 


Rect 
Recs 
Word; 


{ described in Table 4 } 

( described in Table 4 } 

{ source rectangle } 

( destination rectangle } 

{ transfer mode (may include new transfer modes) } 
{ described in Table 4 ) 


packed copybits, rgn clipped 


Rect 
Rect 
Word; 
Rgn; 


{ described in Table 4 } 

{ described in Table 4 } 

{ source rectangle } 

{ destination rectangle } 

{ transfer mode (may include new transfer modes) } 
{ region for masking } 

( described in Table 4 ) 


Table 4. Data types found within new PICT opcodes listed in Table 3 


Opcode Name 


pixMap = 


aa 
a 
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end; 


baseAddr: long; 
rowBytes: 
Bounds: - 
version: 
packType: 
packSize: 
hRes: 
vRes: 
pixelType: 
pixelSize: 
empCount: 
cnpSize: 


planeBytes: 


pmTable: 


pmReserved: long; 


word; 
rect 
word; 
word: 
long; 
fixed; 
fixed; 
word; 
word; 
word; 
word; 
long; 
long; 


Description 


{ unused =0) 

{ rowBytes w/high byte set } 

{ bounding rectangle } 

{ version number = 0 } 

{ packing format = 0 } 

( packed size = 0 } 

{ horizontal resolution (default = $0048.0000) } 
{ vertical resolution (default = $0048.0000) } 

{ chunky format = 0 } 

{ # bits per pixel (1,2,4,8) } 

( # components in pixel = 1 } 

{ size of each component = pixelSize for chunky } 
( offset to next plane = O } 

{ color table = 0 } 

{ reserved =0 } 
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Table 4. Data types found within new PICT opcodes listed in Table 3 (continued) 


i emma 


Opcode Name Description 


colorTable = ctseed: long; ( id number for color table = O } 
transIndex: word; ( flags word = 0 } 
ctSize: word; ( number of ctTable entries-1 } 
{ ctSize + 1 color table entries } 
( each entry = pixel value, red, green, blue: word ) 


end; 


pixData: If rowBytes < 8 then data is unpacked 
data size = rowBytes*(bounds.bottom-bounds.top); 
If rowBytes >= 8 then data is packed. 
image contains (bounds. bottom-bounds.top) packed scanlines. 
Packed scanlines are produced by the PackBits routine. 
Each scanline consists of (byteCount] (data). 
If rowBytes > 250 then byteCount is a word, else it is a byte. 


end; 
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YOU SHOULD CAREFULLY READ THE FOLLOWING 
TERMS AND CONDITIONS BEFORE USING THIS 
SOFTWARE. ANY DOWNLOADING, REPRODUCTION, 
COPYING OR OTHER USE OF THE SOFTWARE WILL 
CONSTITUTE ACCEPTANCE OF THESE TERMS AND 
CONDITIONS. 


SINGLE-COMPUTER END USER 
SOFTWARE LICENSE AGREEMENT 
APPLE COMPUTER, INC. (“Apple”) provides this software 
and licenses its use. You assume responsibility for the selection 
of the software to achieve your intended results, and for the 
installation and use of, and results obtained from, the software. 





LICENSE 
Pursuant to this license you may: 

1. Use the software only on a single Apple computer. You 
must obtain 2 supplementary license from Apple before 
using the software in connection with systems and multiple 
central processing units, computer networks or emulations 
on mainframe or municomputers. 

2. Download the software only on media that is compatible 
with Apple manufactured computers. 

3. Copy the software into any machine readable form for 
backup purposes in support of your use of the software on 
the single Apple computer. 

4. Transfer the software and license to another party with a 
copy of this Agreement provided the other party reads and 
agrees to accept the terms and conditions of this Agreement. 
If you transfer the software, you must at the same ume 
either transfer all copies, whether in printed or machine- 
readable form, to the same party or destroy any copies not 
transferred. Apple grants a license to such other party under 
this Agreement and the other party will accept such license 
by its initial use of the software. If you transfer possession 
of any copy of the software, in whole or in part, to another 
party, your license is automatically terminated. 

This software is protected by United States copyright law. 
You must reproduce the Apple copyright notice on any copy of 
the software. 

THIS SOFTWARE MAY BE ELECTRONICALLY DIS- 
TRIBUTED ONLY BY AUTHORIZED ELECTRONIC 
DISTRIBUTORS. IT MAY BE DOWNLOADED ONLY FOR 
PERSONAL OR NON-COMMERCIAL USES ON APPLE 
COMPUTERS AND MAY NOT BE REDISTRIBUTED OR 
USED FOR COMMERCIAL PURPOSES WITHOUT AN 
EXPRESS SOFTWARE DISTRIBUTION LICENSE FROM 
APPLE. These licenses are available from Apple's Software 
Licensing Department. 

YOU MAY NOT MODIFY, REVERSE COMPILE, DISAS- 
SEMBLE, NETWORK, RENT, LEASE, LOAN OR DIS- 
TRIBUTE THE SOFTWARE, OR ANY COPY, IN WHOLE 
OR IN PART. YOU UNDERSTAND THAT UNAUTHOR- 
IZED REPRODUCTION OF COPIES OF THE SOFTWARE 
OR UNAUTHORIZED TRANSFER OF ANY COPY OF THE 
SOFTWARE MAY SUBJECT YOU TO A LAWSUIT FOR 
ee INJUNCTIVE RELIEF, AND ATTORNEY'S 

5. 
Apple reserves all rights not expressly granted to you. 


Export law assurances 


You agree and certify that neither the software and documen- 
tation nor any direct uct thereof (1) is intended to be used 
for nuclear proliferation or any other purpose prohibited by the 
United States Export Administration Act of 1979, as amended 
(the “Act”) and the regulations promulgated thereunder, and 
(2) is being or will be downloaded, shipped, transferred or 
reexported, directly or indirectly, into any country prohibited 
by the Act and the regulations promulgated thereunder. 


Government End Users 

If you are acquiring the software on behalf of any unit or 
agency of the United States government, you agree that: (a) the 
software is “Commercial Computer Software” as that term is 


defined in Paragraph 27.401 of the DoD Supplement to the 
Federal Acquisition Regulations (the “Supplement”) or is 
within the equivalent classification of any other federal agen- 
cies’ regulations; (b) the software was developed at private 
expense, and no part of it was developed with goverment 
funds; (c) the government's use of the software is subject to 
“Restricted Rights” as that term is defined in clause 
52.227-7013 (b)(3)(1i) of the Supplement or in the equivalent 
clause of any other federal agencies' regulations; (d) the 
software is a “trade secret” of Apple for all purposes of the 
Freedom of Information Act; and (e) each copy of the 
software will contain the following Restricted Rights Legend: 
“Restncted Rights Legend” 

Use, duplication or disclosure is subject to restrictions as 

set forth in subdivision (b)(3)(ii}) of the Rights in 

Technical Data and Computer Software clause at FAR 

52.227-7013. Manufacturer: Apple Computer, Inc. 

20525 Mariani Avenue, Cupertino, Calfornia 5014. 

You agree to indemnify Apple for any liability, loss, costs 
and expense (including court costs and reasonable attorneys’ 
fees) arising out of any breach of the provisions of this 
Agreement relating to use by the government 


Term 


The license is effective until terminated. You may terminate it 
at any time by destroying the software together with all copies. 
The license will also terminate upon conditions set forth else- 
where in this Agreement or if you fail to comply with any of 
the terms or conditions of this Agreement. You agree upon 
such termination to destroy all copies of the software. 


Disclaimer of Warranty 


The software is provided “as is” without warranty of any 
kind, either express or implied, with respect to its merchant- 
ability or its fimess for any particular purpose. The entire nsk 
as to the quality and performance of the software is with you. 
Should the software prove defective, you (and not Apple or an 
Apple authorized representative) assume the entire cost of all 
necessary servicing, repair or correction. 

Apple does not warrant that the functions contained in the 
software will meet your requirements or that the operation of 
the software will be uninterrupted or error free or that defects in 
the software will be corrected. 

Some states do not allow the exclusion of implied warranties, 
so the above exclusion may not apply to you. This warranty 
gives you specific legal rights and you may also have other 
nghts which vary from state to state. 


Limitation of Remedies 


In no event will Apple be liable to you for any lost profits, 
lost savings or other incidental, special or consequential 
damages arising out of the use of or inability to use any soft- 
ware even if Apple or an authorized Apple representative has 
been advised of the possibility of such damages, or for any 
claim by any other party. 

Some states do not allow the limitation or exclusion of 
liability for incidental or consequential damages so the above 
limitation or exclusion may noi apply to you. 

Apple's liability to you for actual damages for any cause 
whatsoever, and regardiess of the form of the action, will be 
limited to the greater of $500 or the money paid for the soft- 
ware that caused the damages or that is the subject matter of, or 
is directly related to, the cause of action. 


General 


This Agreement, if any attempt to network, rent, lease, or 
sublicense the software, or, except as expressly provided tn 
this Agreement, to transfer any of the rights, duties or obliga- 
tions under this Agreement, becomes void. 

The Agreement will be construed under the laws of the state 
of California, except for that body of laws dealing with conflict 
of laws. If any provision of this Agreement shall be held by a 
court of competent jurisdiction to be contrary to law, that pro- 
vision will be enforced to the maximum extent permissible, 
and the remaining provisions of this Agreement shall remain in 
full force and effect. 


(o 
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Example Applications and Sources 


The files included on the Examples 1, 2 and 3 disks are example programs designed for use with 
various programming environments, mostly the Lisa Workshop. These disks are in Macintosh 
format and the files are text-only files, so anyone with a Macintosh editor or word processor can 
read the source code. However the Lisa Pascal Workshop is required to compile most of the 
examples, most of which are written in Lisa Pascal. 


If you plan to read the Examples disks from a Macintosh, note that they have no System folder so 
they cannot be used to boot a Macintosh; to use them you must boot another disk first. 


Macintosh 68000 Development System (MDS) users can assemble the DefProc (definition 
procedure) files. The INCLUDE statements must be modified, as described in the files. MDS may 
return minor warnings which may be ignored. 


A Workshop exec file is provided to translate the Macintosh text only files to Lisa text files and 
copy them from Macintosh disks to a Lisa hard disk. This exec file is on the Examples 1 disk. 
Use MacCom to transfer it to a Lisa, and run it on the Lisa as described below. Users who do not 
wish to copy all the examples (which require 1640 blocks of disk space) should move selected files 
onto another Macintosh disk or modify the exec files appropriately. 


Invoke the convert file as follows: 

R<convert/Mac2Lisa 
The exec file will prompt the user for the Examples 1 and Examples 2 disks and will invoke 
MacCom to copy and convert the files. 


The example disks contain the following files: 


Examples 1: 

Example Application Sources Folder 
'Lisa/EXAMPLE/BOXES.TEXT' 
'Lisa/EXAMPLE/BOXESR. TEXT' 
'Lisa/EXAMPLE/BOXSPHERE. TEXT’ 
'Lisa/EXAMPLE/BOXSPHERER.TEXT' 
'Lisa/EXAMPLE/CONTROL.TEXT' 
'Lisa/EXAMPLE/CONTROLR.TEXT' 
'Lisa/EXAMPLE/DEBUGWINDON. TEXT ' 
'Lisa/EXAMPLE/DEBUGWINDOWR. TEXT' 
'Lisa/EXAMPLE/EVENT TUTOR. TEXT' 
'Lisa/EXAMPLE/EVENT TUTORR.TEXT' 
'Lisa/EXAMPLE/FILE.TEXT' 
'Lisa/EXAMPLE/FILEASM, TEXT' 
'Lisa/EXAMPLE/FILER. TEXT ' 
'Lisa/EXAMPLE/GRONW. TEXT" 
'Lisa/EXAMPLE/GROWR. TEXT' 
'Lisa/EXAMPLE/MENU. TEXT' 
'Lisa/EXAMPLE/MENUR. TEXT' 
'Lisa/EXAMPLE/MODAL. TEXT ' 
'Lisa/EXAMPLE/MODAL1.TEXT' 
'Lisa/EXAMPLE/MODALIR. TEXT' 
'Lisa/EXAMPLE/MODAL2.TEXT' 
'Lisa/EXAMPLE/MODAL2R. TEXT' 
'Lisa/EXAMPLE/MODALR. TEXT" 
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Move 


'Lisa/EXAMPLE/MODELESS. TEXT' 
'Lisa/EXAMPLE/MODELESSR. TEXT’ 
'Lisa/EXAMPLE/PICSCRAP.TEXT' 
'Lisa/EXAMPLE/PICSCRAPR.TEXT' 
'Lisa/EXAMPLE/PRINT.TEXT' 
'Lisa/EXAMPLE/PRINTR.TEXT' 
'Lisa/EXAMPLE/QDSAMPLE. TEXT' 
'Lisa/EXAMPLE/QDSAMPLER. TEXT '! 


These To A Lisa Folder 
"convert /MAC2LISA.TEXT' 
"EXAMPLE /EXAMPLELIST. TEXT" 
'EXAMPLE/EXEC. TEXT" 
'EXAMPLE/EXECALL, TEXT" 

"Ee XAMPLE/EXECALL2.TEXT' 
"EXAMP LE/GRAF3DLINK.TEXT' 
'EXAMPLE/MAXLINK. TEXT' 
"'EXAMPLE/MINLINK. TEXT' 
'EXAMPLE/PRINTLINK.TEXT' 
'EXAMPLE/SANELINK. TEXT ' 
"EXAMPLE/SPEECHLINK. TEXT ' 
"EXAMPLE/VANILLAEXEC. TEXT' 
'EXAMPLE/WRITELNLINK. TEXT' 


Examples 2 Disk: 


Desk Accessory Examples Folder 


Pascal Desk Accessory Folder 
'Lisa/EXAMPLE/ADESKACC. TEXT' 
'Lisa/EXAMPLE/ADESKACCR. TEXT' 
'Lisa/EXAMPLE/UNAMACC. TEXT" 
'Lisa/EXAMPLE/UNAMACCASM.TEXT' 
'Lisa/EXAMPLE/UNAMACCR. TEXT' 
'Lisa/EXAMPLE/UNAMACCX. TEXT ' 


Uriah (MDS) Folder 
UriahMac 
UriahnhMac.Asm 
UriahMac. Link 
UriahMac.R 


Example Application Sources2 Folder 


'Lisa/EXAMPLE/SAMP .TEXT' 
'Lisa/EXAMPLE/SAMPR. TEXT ' 
'Lisa/EXAMPLE/SCROLL.C.TEXT' 
'Lisa/EXAMPLE/SCROLL.TEXT' 
'Lisa/EXAMPLE/SCROLLR.TEXT' 
'Lisa/EXAMPLE/SFSAMPLE.TEXT' 
'Lisa/EXAMPLE/SFSAMPLER., TEXT' 
'Lisa/EXAMPLE/SHOWPAINT. TEXT" 
'Lisa/EXAMPLE/SHOWPAINTR.TEXT' 
'tLisa/EXAMPLE/SINEGRID. TEXT" 
'Lisa/EXAMPLE/SINEGRIDR. TEXT" 
'Lisa/EXAMPLE/SKEL. TEXT ' 
'Lisa/EXAMPLE/SKELR. TEXT ' 
'Lisa/EXAMPLE/SOUNDLAB, TEXT ' 
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'Lisa/EXAMPLE/SOUNDLABR. TEXT ' 
'tisa/EXAMPLE/SPEAKFILE. TEXT’ 
'Lisa/EXAMPLE/SPEAKFILER.TEXT' 
'Lisa/EXAMPLE/TEXTEDIT.TEXT' 
'Lisa/EXAMPLE/TEXTEDITR. TEXT’ 
'Lisa/EXAMPLE/WINDONW. TEXT' 
'Lisa/EXAMPLE/WINDOWR. TEXT ' 


List Manager Examples Folder 
LDEFPROCO. TEXT 
list-test 
LIST TESI; TEXTI 
'LIST/TESTEXEC. TEXT' 
'LIST/TESTR. TEXT' 


MDS Graf3D Example Folder 
BoxSphere 
BoxSphere.Asm 
BoxSphere.Job 
BoxSphere.Link 
BoxSphere.Rel 


SCSI Example Folder 
SCSIDisk.a 


SFPut, GetFile Examples Folder 
SFGETDEMO. TEXT 
SFGETDEMOR. TEXT 
SFPGETDEMO. TEXT 
SFPGETDEMOR. TEXT 
SFPutDemo.p 
SFPutDemo.r 


Examples 3 Disk: 

DefProc Sources Folder 
'DEFPROCS/BUTCDEF.TEXT' 
'DEFPROCS/MDEF. TEXT' 
'DEFPROCS/RDOCWDEF . TEXT" 
'DEFPROCS/SBARCDEF .TEXT' 
'DEFPROCS/WDEF. TEXT" 


Example Applications Folder 
Bone 
Boxes 
BoxSphere 
Control 
DebugWindow 
"Event Tutor' 
File 
Grow 
Instructions 
Life 
MacPic 
Menu 
Modal 
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Modall 
Modal2 
Modeless 
"More Info' 
PicScrap 
Print 
QDSample 
Samp 
Scroll 
SFPutDemo 
SFSample 
ShowPaint 
SineGrid 
Skel 
SoundLab 
TextEdit 
Window 


Source Fragments Folder 
'FRAGMENT/APPLETALK 1.TEXT' 
'FRAGMENT/APPLETALK 2.TEXT' 
'FRAGMENT/APPLETALK 3.TEXT' 
'FRAGMENT/APPLETALK 4.TEXT"' 
'FRAGMENT/ZOOMRECT.TEXT' 

' IMAGEWRITER/RESDEF . TEXT" 
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The files on these disks are example programs (how to use controls, windows, dialogs, 
etc.), example exec files, definition procedures, and sample desk accessories. 


example/ADeskAcc.text 
example/ADeskAccR.text 


example/Boxes.text 
example/BoxesR.text 


example/BoxSphere.text 
example/BoxSphereR.text 


example/Control.text 
example/ControlR.text 


example/DebugWindow.text 
example/DebugWindowR.text 


example/Event Tutor.text 
example/Event TutorR.text 


example/File.text 
example/FileAsm.text 


example/FileR.text 


example/Grow.text 
example/GrowR.text 


example/Menu.text 
example/MenuR.text 


example/Modal.text 
example/ModalR.text 


example/Modall.text 
example/ModallR.text 


example/Modal2.text 
example/Modal2R.text 


example/Modeless.text 
example/ModelessR.text 


example/PicScrap.text 
example/PicScrapR.text 


example/Print .text 
example/PrintR.text 


example/QDSample.text 
example/OQDSampleR.text 


example/Samp.text 
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Uriah, a sample desk accessory written in assembly language 
this resource definition file explains how to build it 

(there is no exec file) 

MDS users--see UriahMac.Asm instead 

a Graf3D example 

another Graf3D example 

a Control example 

a WritelnWindow example 

a tool from Dartmouth to teach programmers about 

events; the resulting application it is worth looking at 


the File example, a text processor, has lots of stuff in it 
an assembly module for File 

(note: File has been cleaned up since the Feb. Supplement) 
a Window example 

a Menu Manager example 

a Modal Dialog example 

another Modal Dialog example 

and another Modal Dialog example 

a Modeless Dialog example 

an example of how to get pictures from the 

scrapbook 

a Print Manager Example 


a QuickDraw example 


the Samp example from inside Macintosh 
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example/SampR.text 


example/Scroll.text 
example/ScrollR.text 


example/SFSample.text 
example/SFSampleR.text 


example/ShowPaint .text 
example/ShowPaintR.text 


example/SineGrid.text 
example/SineGridR.text 


example/Skel.text 
example/SkelR.text 


example/SoundLab. text 
example/SoundLabR.text 
example/SpeakFile.text 


example/SpeakFileR.text 


example/TextEdit .text 
example/TextEditR.text 


example/Window.text 
example/WindowR.text 


dit 
a Control Manager example--scrolling 


an example which displays a dialog that looks 
like Standard File (e.g. SFGetFile) 


how to unpack a MacPaint document 


another Graf3D example 


a skeleton program from Dartmouth-- 

definitely worth looking at 

a Sound Driver example--uses SANE floating point in 
Pascal Workshop 3.9; may blow up on a Macintosh XL 
(better written sound software would not blow up) 


a MacinTalk (speech synthesis) example 


a Text Edit example 


a Window Manager example 


We have also included an example of how to write a desk accessory in Pascal. It's called uNamacc. 
You need to have the new Workshop 3.9 partial linker to compile and link this. 


example/UNamAcc.text 
example/UNamAccAsm.text 
example/UNamAccR.text 
example/UNamAcckX.text 


the Pascal source 

an assembly language portion 

RMaker source (resource definition file) 
the exec file for UNamAcc 


There are several exec files for use with these examples on the Examples 1 disk. These exec files 


are designed to work with the 3.0 or 3.9 Workshops.Note that not all of the above Pascal source files 
contain the $M+ code generator option; that option must be included in the source and/or the exec file. 
We include it in our exec files. 


The file example/Exec.text is a general purpose, semi-smart exec file that checks to see if the files 
you give it exist, and whether the files have changed since the last time you compiled or assembled. It 
sets the bundle bit in RMaker if (and only if) you give it a creator. To invoke it you would type: 


R<example/Exec (Pascal file, assembly file, resource file, creator, link file, 
source volume) 


All of the items in the parentheses are optional. The default file is example/Window. The assembly file 
is assumed to be appended by ‘asm’, and the resource file is assumed to be appended by 'R, like this: 


example/file.text 
example/fileAsm.text 


Pasca! Source 
Assembly source 
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RMaker source (resource definition) example/fileR.text 


The link file is a file that contains the names of the files needed to link your program with. The 
default file name is example/MinLink. 


example /VanillaExec.text is an exec for those who would rather build without worrying about 
the details of whether the file has a creator or what files to link with. It assumes that the files are 
named using the conventions described above. It doesn't assemble. It links with everything. All of 
the files linked are commented as to when you would need them. It deletes the Desktop file when 
you run MacCom and it sets the bundle bit in RMaker whether you have a creator or not. To run it 
you enter: 


R<example/VanillaExec(filename, creator) 


There are also a set of files that allow you to build all of the examples at one time. They compile, 
link, make the resource file, and run MacCom to build each example and load it onto a Macintosh 
disk. They do not eject the disk until all the applications have been built. They do not work with 
the desk accessory examples. 


example/ExecAll.text this is the main exec--type R<example/ExecA11 to run it 

example/ExecAll2.text This is very much like example /Exec, with some 
modifications 

example/ExampleList.text This file has a list of each example filename, creator, and 


link file if there is one. ExecAll reads this to determine 
what to exec. 


Note that ExecAll can be invoked with any list of files in the format of ExampleList as follows: 
R<example/ExecAl1(MyExampleList.text) 


There are also a number of LINK files. These contain filesnames that are fed into the linker during 
the exec process. 


example/MinLink.text The minimum of files needed to link. 
example/MaxLink.text The maximum of files--everything. 
example/WritelnLink.text The files needed for the WritelnWindow unit. 
example/Graf3DLink.text The files needed for Graf3D. 
example/PrintLink.text The files needed for printing. 
example/SANELink.text The files needed for SANE. 
example/SpeechLink.text The files needed for MacinTalk (speech synthesis). 


Other files on the Examples disks include fragment / files, defProcs/ files, 
example/Scroll.C.text and ImageWriter/ResDef .text. 


The fragment / files are Lisa Pascal source fragments; these include the four Pascal AppleTalk 
example fragments from the final Inside Macintosh (better examples will appear in a future 
Technical Note) and a code fragment which draws the "zooming" rectangles which the Finder uses 
when opening and closing windows. 





The defProcs/ files are the assembly language definition procedures for the standard buttons, 
menus, scroll bars, windows, and round-cornered windows, included here in case you need to 
write your own custom definitions. 


The file example/Scroll.C.text is the Pascal program example/Scroll.text rewritten in a 
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vanilla version of the language C (it may need modification before it can be compiled with a 
particular C compiler). 


The file tmageWriter/ResDef .text is the resource definition file fragment described in the 
enclosed document titled The March 1985 ImageWriter: Programmers’ Notes. 


The List Manager Examples folder contains the sources to a Lisa Pascal application which 
uses the List Manager. 


An example program which uses the Graf3D routines isin the MDS Graf3D Example folder. 
The SCSI Example folder contains an assembly language SCSI driver. 


Inthe SFPut, GetFile Examples folder are example code for SFPutFile and SFGetFile. 
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YOU SHOULD CAREFULLY READ THE FOLLOWING 
TERMS AND CONDITIONS BEFORE USING THIS 
SOFTWARE. ANY DOWNLOADING, REPRODUCTION, 
COPYING OR OTHER USE OF THE SOFTWARE WILL 
CONSTITUTE ACCEPTANCE OF THESE TERMS AND 
ZONDITIONS. 


SINGLE-COMPUTER END USER 
SOFTWARE LICENSE AGREEMENT 
APPLE COMPUTER, INC. (“Apple”) provides this software 
and licenses its use. You assume responsibility for the selection 
of the software to achieve your intended results, and for the 
installation and use of, and results obtained from, the software. 





LICENSE 
Pursuant to this license you may: 

1. Use the software only on a single Apple computer. You 
must obtain a supplementary license from Apple before 
using the software in connection with systems and multiple 
central processing units, computer networks or emulations 
on mainframe or minicomputers. 

2. Download the software only on media that is compatible 
with Apple manufactured computers. 

3. Copy the software into any machine readable form for 
backup purposes in support of your use of the software on 
the single Apple computer. 

4. Transfer the software and license to another party with a 
copy of this Agreement provided the other party reads and 
ee 

you transfer the software, you must at the same time 
either transfer all copies, whether in printed or machine- 
readable form, to the same or destroy any copies not 
transferred. Apple grants a license to such other party under 
this Agreement and the other party will accept such license 
by its initial use of the software. If you transfer possession 
of any copy of the software, in whole or in part, to another 

, your license is automatically terminated. 


fi is software is protected by United States copyright law. 


Se nan reproduce the Apple copyright notice on any copy of 
e software. 

THIS SOFTWARE MAY BE ELECTRONICALLY DIS- 
TRIBUTED ONLY BY AUTHORIZED ELECTRONIC 
DISTRIBUTORS. IT MAY BE DOWNLOADED ONLY FOR 
PERSONAL OR NON-COMMERCIAL USES ON APPLE 
COMPUTERS AND MAY NOT BE REDISTRIBUTED OR 
USED FOR COMMERCIAL PURPOSES WITHOUT AN 
EXPRESS SOFTWARE DISTRIBUTION LICENSE FROM 
APPLE. These licenses are available from Apple's Software 


Licensing t. 

YOU MAY NOT MODIFY, REVERSE COMPILE, DISAS- 
SEMBLE, NETWORK, RENT, LEASE, LOAN OR DIS- 
TRIBUTE THE SOFTWARE, OR ANY COPY, IN WHOLE 
OR IN PART. YOU UNDERSTAND THAT UNAUTHOR- 
IZED REPRODUCTION OF COPIES OF THE SOFTWARE 
OR UNAUTHORIZED TRANSFER OF ANY COPY OF THE 
SOFTWARE MAY SUBJECT YOU TO A LAWSUIT FOR 
Eee INJUNCTIVE RELIEF, AND ATTORNEY'S 

Apple reserves all rights not expressly granted to you. 


Export law assurances 

You agree and certify that neither the software and documen- 
tation nor any direct thereof (1) is intended to be used 
for nuclear proliferation or any other purpose prohibited by the 
United States Export Administration Act of 1979, as amended 
(the “Act”) and the regulations promulgated thereunder, and 
(2) is being or will be downloaded, shipped, transferred or 
reexported, directly or indirectly, into any country prohibited 
by the Act and the regulations promulgated thereunder. 
See 


Government End Users 


E resi me ehhh da 
agency of the United States government, ou agree that: (a) the 
E so is “Commercial Computer Software as that term is 


da 


defined in Paragraph 27.401 of the DoD Supplement to the 
Federal Acquisition Regulations (the “Supplement") or is 
within the equivalent classification of any other federal agen- 
cies' regulations; (b) the software was developed at private 
expense, and no part of it was developed with goverment 
funds; (c) the government's use of the software is subject to 
“Restricted Rights” as that term is defined in clause 
§2.227-7013 (b)(3)(ii) of the Supplement or in the equivalent 
clause of any other federal agencies’ regulations; (d) the 
software is a “trade secret” of Apple for all purposes of the 
Freedom of Information Act; and (e) each copy of the 
software will contain the following Restricted Rights Logan 
"Restricted Rights Legend” 

Use, duplication or disclosure is subject to restrictions as 

set forth in subdivision OOD of the Rights in 

Technical Data and Computer Software clause at FAR 

$2.227-7013. Manufacturer: Apple Computer, Inc. 

20525 Mariani Avenue, Cupertino, Calfornia 5014. 

You agree to indemnify Apple for any liability, loss, costs 
and expense (including court costs and reasonable attorneys’ 
fees) arising out of any breach of the provisions of this 
Agreement relating to use by the government. 


Term 

The license is effective until terminated. You may terminate it 
at any time by destroying the software together with all copies. 
The license will also terminate upon conditions set forth else- 
where in this Agreement or if you fail to ly with any of 
the terms or conditions of this Agreement. You agree upon 
such termination to destroy all copies of the 


Disclaimer of Warranty 


The software is provided “as is” without warranty of any 
kind, either express or implied, with respect to its merchant- 
ability or its fimess for any particular The entire risk 
as to the quality and performance of the software is with you. 
Should the software prove defective, you (and not Apple or an 
Apple authorized representative) assume the entire cost of all 
necessary servicing, repair or correction. 

Apple does not warrant that the functions contained in the 


software will meet your requirements or that the operation of 
the software will be unin or error free or that defects in 
the software will be correc 


Some states do not allow the exclusion of implied warranties, 
so the above exclusion may not apply to you. This warranty 
gives you specific legal rights and you may also have other 
Tights which vary from state to state. 


Limitation of Remedies 


In no event will Apple be liable to you for any lost profits, 
lost savings or other incidental, ial or consequential 
damages arising out of the use of or inability to use any soft- 
ware even if Apple or an authorized a le representative has 
been advised of the possibility of damages, or for any 
claim by any other party. 

Some states do not allow the limitation or exclusion of 
liability for incidental or consequential damages so the above 
limitation or exclusion may not apply to you. 

Apple's liability to you for actual damages for any cause 
whatsoever, and regardless of the form of the action, will be 
limited to the greater of $500 or the money paid for the soft- 
ware that caused the damages or that is the subject matter of, or 
is directly related to, the cause of action. 


General | 

This Agreement, if any attempt to network, rent, lease, or 
sublicense the software, or, aT as expressly provided in 
this Agreement, to transfer any of the rights, duties or obliga- 
tions under this Agreement, becomes void. 

The Agreement will be construed under the laws of the state 
of California, except for that body of laws dealing with conflict 
of laws. If any provision of this Agreement shall be held by a 
court of com t jurisdiction to be contrary to law, that 
vision will be enforced to the maximum extent permissible, 
and the remaining provisions of this Agreement shall remain in 
full force and effect. e 
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